@onlyworlds/sdk 4.11.0 → 4.12.0

package/AGENTS.md

@@ -40,6 +40,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Images: `uploadImage(bytes)` returns `{ url, ... }`; set `url` as `image_url`. The bytes go
   to the edge with a single-use ticket from keel, never with the API key. `removeImage(urlOrKey)`
   takes one back (its uploader or the world's owner); it leaves `image_url` on elements as is.
+- Invite links (since 4.12.0): `previewJoin(code)` (no credential sent) shows who invites, to
+  which world, in what role; `acceptJoin(code)` with an `ow_a_` account token joins. Bad code:
+  `err.isNotFound`; `err.isAlreadyMember`, `err.isPinRequired` for the two 409s.
 - Lookup without a model (since 4.11.0): `buildWorldIndex(elements)` then
   `lookupWorld(index, question)` ranks the elements a question is about (names, then kind, one
   link step, then text); `renderElement(el, index)` is a compact card with links by name.

package/CHANGELOG.md

@@ -5,6 +5,21 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.12.0] — 2026-10-12
+
+### Added
+- **Joining a world by link (keel #212).** `previewJoin(code)` reads what a join code holds
+  without using it (`OwJoinPreview`: `reader`, `world`, `invited_by`, `owner_character`,
+  `role`, `with_character`, `expires_at`) and sends no credential, whatever key the client
+  holds. `acceptJoin(code)` accepts an invite link as the account behind the client's `ow_a_`
+  token and returns the new membership (`OwJoinedMembership`, `roster_character` included);
+  a world key is a `TypeError` before anything is sent. New getters on `OwApiError`:
+  `isNotFound` (every bad code is one 404), `isAlreadyMember` and `isPinRequired` (the two
+  409s, told apart by code). Shapes read from keel's code (`accounts/join_api.py`,
+  `accounts/api.py`), since the OpenAPI document gives no response bodies for these routes.
+  Checked live: a bad code on production answers `isNotFound`. A real accept has not been
+  run from here (no account token); Lantern's door is its first live use.
+
 ## [4.11.0] — 2026-10-12
 
 ### Added

package/README.md

@@ -110,6 +110,17 @@ await writer.patch('character', id, { image_url: null });
 
 The image's uploader or the world's owner can remove an uploaded image; the space goes back to the uploader's storage. Removal leaves elements as they are, so clear their `image_url` yourself (`createRemovalTicket(key).referenced` says how many still show it). A copy the network already holds can keep answering for a while.
 
+## Invite links
+
+A world's owner can invite a person with a link (`https://www.onlyworlds.com/join#ow_j_…`). The code is the part after `#`:
+
+```typescript
+const invite = await client.previewJoin(code);   // who invites, which world, what role; sends no key
+const membership = await account.acceptJoin(code); // account = a client with an ow_a_ token
+```
+
+A bad code (unknown, used, revoked, expired) is one 404 (`err.isNotFound`). Accepting can answer `err.isAlreadyMember` or `err.isPinRequired` (set a PIN first); a refusal never uses up the code.
+
 ## Sync
 
 ```typescript

package/dist/index.d.ts

@@ -1988,6 +1988,37 @@ interface OwRemovalTicket {
     referenced: number;
 }
 /** The edge's 200 for one removal. */
+/** POST /join/preview: what a join code holds, read without using it (keel #212). */
+interface OwJoinPreview {
+    /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. */
+    reader: 'person' | 'agent' | (string & {});
+    world: {
+        name: string;
+        description: string | null;
+    };
+    /** The name the inviter signed the link with, or null. */
+    invited_by: string | null;
+    /** The world owner's chosen Character's name, never a username; null when none is set. */
+    owner_character: string | null;
+    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    /** Whether joining gives the joiner a Character of their own (agent links). */
+    with_character: boolean | null;
+    /** ISO 8601, UTC. */
+    expires_at: string;
+    [k: string]: unknown;
+}
+/** POST /account/join: the new membership (the same row as accepting an email invite). */
+interface OwJoinedMembership {
+    /** The membership's id. */
+    id: string;
+    world_id: string;
+    world_name: string;
+    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    joined_at: string | null;
+    /** The id of the joiner's roster Character, or null. */
+    roster_character: string | null;
+    [k: string]: unknown;
+}
 interface OwRemovedImage {
     /** The object key that was removed. */
     removed: string;
@@ -2139,6 +2170,12 @@ declare class OwApiError extends Error {
      * is now, so no second read is needed.
      */
     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;
+    /** 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. */
+    get isPinRequired(): boolean;
 }
 /**
  * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
@@ -2368,6 +2405,23 @@ declare class OwV2Client {
     removeImage(keyOrUrl: string, opts?: {
         ticket?: OwRemovalTicket;
     }): Promise<OwRemovedImage>;
+    /**
+     * POST /join/preview -- what a join code holds, without using it: who invites, to
+     * 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 `#`.
+     */
+    previewJoin(code: string): Promise<OwJoinPreview>;
+    /**
+     * POST /account/join -- accept an invite link's code as the account this client's
+     * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
+     * (every bad code, and a code made for an AI agent), 409 `already_member`
+     * (`err.isAlreadyMember`) and 409 `pin_required` (`err.isPinRequired`: the account
+     * has no PIN yet). A refusal never spends the code. A world key here is a TypeError
+     * before anything is sent.
+     */
+    acceptJoin(code: string): Promise<OwJoinedMembership>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -3009,4 +3063,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };
+export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, 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 OwMediaTicket, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };

package/dist/index.js

@@ -75,6 +75,18 @@ var OwApiError = class extends Error {
   get isPreconditionFailed() {
     return this.status === 412 && this.code === "precondition_failed";
   }
+  /** 404 `not_found`: no such element or route, or a join code that is unknown, used, revoked or expired. */
+  get isNotFound() {
+    return this.status === 404 && this.code === "not_found";
+  }
+  /** 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";
+  }
+  /** acceptJoin: the account has no PIN yet, and a member writes with their own (409 `pin_required`). The code is not spent. */
+  get isPinRequired() {
+    return this.status === 409 && this.code === "pin_required";
+  }
 };
 var OwPreconditionFailedError = class extends OwApiError {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -410,6 +422,31 @@ var OwV2Client = class {
     if (!res.ok) throw await errorFromResponse(res);
     return await res.json();
   }
+  // -- Joining a world by link (keel #212) ----------------------------------
+  /**
+   * POST /join/preview -- what a join code holds, without using it: who invites, to
+   * 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 `#`.
+   */
+  async previewJoin(code) {
+    return this.request("POST", "/join/preview", { auth: false, body: { code } });
+  }
+  /**
+   * POST /account/join -- accept an invite link's code as the account this client's
+   * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
+   * (every bad code, and a code made for an AI agent), 409 `already_member`
+   * (`err.isAlreadyMember`) and 409 `pin_required` (`err.isPinRequired`: the account
+   * has no PIN yet). A refusal never spends the code. A world key here is a TypeError
+   * before anything is sent.
+   */
+  async acceptJoin(code) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("acceptJoin needs an account token (ow_a_): a world key cannot join a world");
+    }
+    return this.request("POST", "/account/join", { body: { code } });
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0

package/package.json

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