@onlyworlds/sdk 4.38.0 → 4.40.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.1-dist.26** (canonical 00.32.01).
+**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.
 
@@ -106,6 +106,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   `mcp`, `declared`, `api`, `v1`, `sync`, `server`), and a `/changes` delete carries
   `deleted_by` and `deleted_via`; `isAgentDoor(door)` is true for the first three. An agent
   seat's key is recorded as an agent without the option. Never set it in a tool people use.
+- A guest or player reads what its own Character's sheet links to as a **stub**, marked
+  `known_of: true` (`isKnownOf(el)`): only `id`, `type`, `name`, `description`, `supertype`,
+  `subtype`, `image_url` and the timestamps are real; every other field reads unset, and its
+  files are 404. Render it as known of, never merge its empties over a whole copy, and never
+  write it back: `upsert`, `patch`, `create` and `bulk` throw a TypeError on one before sending.
 - A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
   Slice strings by code point, not by UTF-16 unit.
 - Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon

package/CHANGELOG.md

@@ -5,6 +5,46 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.40.0] - 2026-10-20
+
+The "known of" stub's client half (keel PR 113, B16; keel #421 §7g), live in production since 2026-10-20 13:47.
+
+### Added
+- **`known_of?: true`** on `OwElementBase` (generated; `SCHEMA.md` says it too): present, and true, only on a
+  stub, an element a guest or player reaches only through its own Character's sheet, one step out. A stub
+  keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`, `created_at`, `updated_at`
+  and `change_seq`; every other field reads unset (`""`, `null`, `[]`), `created_by`, `changed_by` and
+  `changed_via` are null, it has no extension fields, and its files are 404. For Lantern and Atlas, which
+  render stubs (Temper).
+- **`isKnownOf(el)`**: true only for `known_of: true`; absent or anything else is a whole element.
+
+### Changed
+- **A stub is never written**: `upsert`, `patch`, `create` and `bulk` throw a `TypeError` before sending a
+  body with `known_of: true` (`bulk` names the item, and sends none of the batch). Stripping the marker would
+  turn keel's 422 into a write that blanks the element for any key that may write it (an owner pushing a
+  player's copy). `known_of` joins the strip list, so any other value of it is never sent.
+
+## [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.

package/SCHEMA.md

@@ -1,12 +1,14 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.1-dist.26** — canonical schema **00.32.01**, published 2026-10-20.
+**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.
 
 **The shape rules** (v2 wire dialect): every element carries `id` (UUID), `name`, optional
 `description`/`supertype`/`subtype`/`image_url`, server-managed `type`/`created_at`/`updated_at`/`change_seq`/`created_by`,
+`known_of: true` only on a stub (an element a guest knows of through its Character's sheet:
+its other fields read unset and are not values; never write a stub back),
 and namespaced extension fields (`x_*` etc.) returned verbatim. Link fields use ONE bare
 name in both read and write (no `_ids` suffix). Single links are `UUID | null`; multi links
 are `UUID[]`. **Links are owned one-way**: the type listed below owns the field (e.g.

package/dist/index.d.ts

@@ -2,7 +2,8 @@
  *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
  *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
  *  bodies -- the key determines the world) and the seven server-managed fields are
- *  added, since they ride every wire body and appear in no element YAML. */
+ *  added, since they ride every wire body and appear in no element YAML; `known_of`
+ *  rides only a stub. */
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
     type: string;
@@ -30,6 +31,8 @@ interface OwElementBase {
     changed_by?: string | null;
     /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, or `server` (keel's own writes). The first three are agent-made. Null for anything last changed before writes recorded it. */
     changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | null;
+    /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
+    known_of?: true;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
     [ext: string]: unknown;
 }
@@ -1955,6 +1958,19 @@ type OwWriteDoor = NonNullable<OwElementBase['changed_via']>;
 declare const AGENT_DOORS: readonly OwWriteDoor[];
 /** Whether a write came through an agent's door (`changed_via` or `deleted_via`); false for null. */
 declare function isAgentDoor(door: OwWriteDoor | null | undefined): boolean;
+/**
+ * Whether an element body is a stub the reader only knows of (keel PR 113, B16; keel #421
+ * §7g): a guest or player reaches it only through its own Character's sheet, one step out.
+ * A stub keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`,
+ * `created_at`, `updated_at` and `change_seq`; every other field reads unset (`""`, `null`,
+ * `[]`), `created_by`, `changed_by` and `changed_via` are null, it carries no extension
+ * fields, and its files answer 404. Those empties are not the element's values and not a
+ * deletion: never merge them over a whole copy, and never write a stub back (this client
+ * refuses to). True only for `known_of: true`; absent or anything else is a whole element.
+ */
+declare function isKnownOf(element: {
+    known_of?: unknown;
+} | null | undefined): boolean;
 /**
  * /changes response. Wire shape verified in keel source (core/changes.py) and
  * pinned here: {cursor, changes, has_more, head}.
@@ -2254,6 +2270,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 +2304,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 +2753,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. */
@@ -2897,7 +2957,11 @@ declare class OwV2Client {
     create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
         idempotencyKey?: string;
     }): Promise<OwElement>;
-    /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+    /**
+     * PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. A known-of
+     * stub (`known_of: true`, see isKnownOf) is a TypeError before sending, here and on every
+     * element write: a PUT of one would blank every field it does not keep.
+     */
     upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
     /**
      * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
@@ -3155,7 +3219,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 +3234,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 +3296,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 +3315,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:
@@ -4316,4 +4403,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_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, 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 OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, 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, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, 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, fieldLabel, fileKindOf, 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_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, 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 OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, 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, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, 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, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, 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

@@ -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";
@@ -401,6 +429,7 @@ var OwV2Client = class {
    * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
+    refuseKnownOf(element, "create");
     const body = sanitizePayload(element);
     if (body.id === void 0 || body.id === null || body.id === "") {
       body.id = opts.idempotencyKey ? keyedId(opts.idempotencyKey, 0) : mintUuid();
@@ -411,8 +440,13 @@ var OwV2Client = class {
       idempotencyKey: opts.idempotencyKey
     });
   }
-  /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+  /**
+   * PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. A known-of
+   * stub (`known_of: true`, see isKnownOf) is a TypeError before sending, here and on every
+   * element write: a PUT of one would blank every field it does not keep.
+   */
   async upsert(type, id, element) {
+    refuseKnownOf(element, "upsert");
     return this.request("PUT", `/${type}/${id}/`, { write: true, body: sanitizePayload(element) });
   }
   /**
@@ -426,6 +460,7 @@ var OwV2Client = class {
    * it for today's unconditional write.
    */
   async patch(type, id, partial, opts = {}) {
+    refuseKnownOf(partial, "patch");
     return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
@@ -464,6 +499,7 @@ var OwV2Client = class {
    * fresh UUIDv7. Ids you supply are kept.
    */
   async bulk(items, opts = {}) {
+    items.forEach((it, index) => refuseKnownOf(it.element, `bulk: items[${index}]`));
     const body = {
       items: items.map((it, index) => {
         const element = sanitizePayload(it.element);
@@ -772,7 +808,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 +825,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 +993,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 +1015,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 });
   }
   /**
@@ -1140,13 +1199,20 @@ var OwV2Client = class {
     return parsed;
   }
 };
-var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq"];
+var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
 function sanitizePayload(payload) {
   if (!payload || typeof payload !== "object") return payload;
   const rest = { ...payload };
   for (const field of READ_ONLY_FIELDS) delete rest[field];
   return rest;
 }
+function refuseKnownOf(payload, where) {
+  if (payload && typeof payload === "object" && payload.known_of === true) {
+    throw new TypeError(
+      `${where}: this body is a known-of stub (known_of: true), not the element: its empty fields are not its values, and writing it would blank them. Write from a whole copy, or send only the fields you mean to change.`
+    );
+  }
+}
 async function endAuthSession(fetchImpl, auth, session) {
   const abort = new AbortController();
   const timer = setTimeout(() => abort.abort(), 5e3);
@@ -2021,6 +2087,9 @@ var AGENT_DOORS = ["seat", "mcp", "declared"];
 function isAgentDoor(door) {
   return door != null && AGENT_DOORS.includes(door);
 }
+function isKnownOf(element) {
+  return element != null && element.known_of === true;
+}
 
 // src/v2/palette.ts
 var FAMILY_COLORS = {
@@ -3516,6 +3585,7 @@ export {
   getElementLabel,
   isAgentDoor,
   isDemoKey,
+  isKnownOf,
   isLeapYear,
   isParseError,
   kindCanWrite,

package/package.json

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