@onlyworlds/sdk 4.11.0 → 4.13.0

package/AGENTS.md

@@ -40,6 +40,12 @@ 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.
+- Ask (since 4.13.0, account token): `buildAskContext(hits, index)` then
+  `account.ask({ worldId, question, context })`; answers only from the context. 50 a day per
+  account (`err.isQuotaExceeded`); `isAskUnavailable`, `isAskFailed` count nothing.
+- 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,38 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.13.0] — 2026-10-12
+
+### Added
+- **Ask your world (keel #159).** `client.ask({ worldId, question, context })` sends a
+  question to keel's AI proxy with the account's `ow_a_` token (a world key is a `TypeError`
+  before sending) and returns `OwAskAnswer` (`answer`, `model`, `stop_reason`, `usage`,
+  `remaining`). The answer comes from `context` only, or is "The world doesn't say.".
+  `buildAskContext(items, index)` turns the elements the user sees (lookup hits or plain
+  elements, in the caller's order, never re-looked-up) into that `context` within keel's
+  limits (`ASK_LIMITS`: 8 items, 2,000 characters each, 12,000 in all, counted in characters
+  as keel counts them) and says what it did: `kept`, `dropped` (past the 8th, or from the first
+  one the total cannot hold, so what is sent is always the top of the list) and `truncated`.
+  New getters: `isQuotaExceeded` (429; `retryAfter` runs to midnight UTC), `isAskUnavailable`
+  (503), `isAskFailed` (502). keel's document gives no request schema for `/account/ask`, so
+  the body (`world_id`, `question`, `context`) is read from keel's code (`accounts/ask.py`).
+  Not yet run live: no crew session holds an account token.
+
+## [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
@@ -150,7 +161,16 @@ hits[0].element; hits[0].reasons;                 // best first, with why each m
 renderElement(hits[0].element, index);            // a short text card, links by name
 ```
 
-Names come first, then supertype and subtype, then one link step in either direction, then the elements' other text. To have a model phrase an answer, give it the cards of the top hits and ask it to answer only from them.
+Names come first, then supertype and subtype, then one link step in either direction, then the elements' other text.
+
+To have an answer written from what you found, OnlyWorlds runs a small AI proxy for signed-in accounts (50 questions a day):
+
+```typescript
+const shown = hits.slice(0, 8);                          // what your screen lists
+const { context, kept } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
+const reply = await account.ask({ worldId, question, context }); // account: a client with an ow_a_ token
+reply.answer;                                            // from those elements only, or "The world doesn't say."
+```
 
 ## World files
 

package/dist/index.d.ts

@@ -1988,6 +1988,51 @@ interface OwRemovalTicket {
     referenced: number;
 }
 /** The edge's 200 for one removal. */
+/** POST /account/ask: keel's AI proxy's answer (keel #159). */
+interface OwAskAnswer {
+    /** The answer, from the context only; "The world doesn't say." when it does not hold one. */
+    answer: string;
+    model: string;
+    stop_reason: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** Questions the account has left today. */
+    remaining: number;
+    [k: string]: unknown;
+}
+/** 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 +2184,18 @@ 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;
+    /** A daily allowance is used up (429 `quota_exceeded`): the world's image tickets, or the account's asks. See retryAfter. */
+    get isQuotaExceeded(): boolean;
+    /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
+    get isAskUnavailable(): boolean;
+    /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
+    get isAskFailed(): boolean;
 }
 /**
  * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
@@ -2368,6 +2425,38 @@ 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>;
+    /**
+     * 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
+     * the user sees). The answer is "The world doesn't say." when the context does not hold
+     * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
+     * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's daily allowance;
+     * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
+     * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
+     * them counts. 422 for a question over 500 characters or context past its limits.
+     */
+    ask(req: {
+        worldId: string;
+        question: string;
+        context: string[];
+    }): Promise<OwAskAnswer>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -2660,6 +2749,45 @@ declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>,
  */
 declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, { descMax, linkMax, incomingMax }?: OwRenderOptions): string;
 
+/**
+ * Context for keel's AI proxy (POST /api/v2/account/ask, Keel #159): the elements a
+ * question is about, as text, within the proxy's limits. The caller passes the
+ * elements it shows the user, in its own order, and gets back exactly which were sent:
+ * the answer's sources are what the user saw, never a second lookup's.
+ *
+ *   const hits = lookupWorld(index, question).slice(0, 8);   // what the screen lists
+ *   const { context, kept } = buildAskContext(hits, index);
+ *   const reply = await account.ask({ worldId, question, context });
+ *
+ * The limits are keel's (accounts/ask.py), counted the way keel counts (characters,
+ * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all.
+ */
+
+/** keel's limits on one ask. */
+declare const ASK_LIMITS: {
+    readonly questionMax: 500;
+    readonly itemsMax: 8;
+    readonly itemMax: 2000;
+    readonly totalMax: 12000;
+};
+interface OwAskContext {
+    /** The texts to send as `context`, in the order given. */
+    context: string[];
+    /** Ids of the elements sent, in order (one per `context` item). */
+    kept: string[];
+    /** Ids of the elements left out: past the 8th, or from the first one the 12,000 total could not hold. */
+    dropped: string[];
+    /** Ids among `kept` whose text was cut to 2,000 characters. */
+    truncated: string[];
+}
+/**
+ * Turn the elements on screen into the proxy's `context`. Takes lookup hits or plain
+ * elements, keeps their order, renders each with `renderElement`, cuts a text over
+ * 2,000 characters, and stops at the 8th or at the first one the 12,000 total cannot
+ * hold, so what is sent is always the top of the list as shown.
+ */
+declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>): OwAskContext;
+
 /**
  * Photo preparation: make a picture from a phone's camera or files ready for
  * `uploadImage` (webp, png, jpeg or avif, at most 15 MB), in the browser,
@@ -3009,4 +3137,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 { ASK_LIMITS, 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 OwAskAnswer, type OwAskContext, 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, buildAskContext, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };

package/dist/index.js

@@ -75,6 +75,30 @@ 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";
+  }
+  /** A daily allowance is used up (429 `quota_exceeded`): the world's image tickets, or the account's asks. See retryAfter. */
+  get isQuotaExceeded() {
+    return this.status === 429 && this.code === "quota_exceeded";
+  }
+  /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
+  get isAskUnavailable() {
+    return this.status === 503 && this.code === "ask_unavailable";
+  }
+  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
+  get isAskFailed() {
+    return this.status === 502 && this.code === "ask_failed";
+  }
 };
 var OwPreconditionFailedError = class extends OwApiError {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -410,6 +434,50 @@ 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 } });
+  }
+  // -- Ask your world (keel #159) -------------------------------------------
+  /**
+   * 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
+   * the user sees). The answer is "The world doesn't say." when the context does not hold
+   * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
+   * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's daily allowance;
+   * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
+   * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
+   * them counts. 422 for a question over 500 characters or context past its limits.
+   */
+  async ask(req) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("ask needs an account token (ow_a_): the proxy meters per account");
+    }
+    return this.request("POST", "/account/ask", {
+      body: { world_id: req.worldId, question: req.question, context: req.context }
+    });
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0
@@ -1834,6 +1902,38 @@ function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMa
   return lines.join("\n");
 }
 
+// src/ask.ts
+var ASK_LIMITS = { questionMax: 500, itemsMax: 8, itemMax: 2e3, totalMax: 12e3 };
+var chars = (s) => [...s].length;
+var cut = (s, n) => [...s].slice(0, n).join("");
+function buildAskContext(items, index) {
+  const out = { context: [], kept: [], dropped: [], truncated: [] };
+  let total = 0;
+  let full = false;
+  for (const item of items) {
+    const el = item && typeof item === "object" && "element" in item ? item.element : item;
+    if (full || out.context.length >= ASK_LIMITS.itemsMax) {
+      out.dropped.push(el.id);
+      continue;
+    }
+    let text = renderElement(el, index);
+    if (chars(text) > ASK_LIMITS.itemMax) {
+      text = cut(text, ASK_LIMITS.itemMax);
+      out.truncated.push(el.id);
+    }
+    if (total + chars(text) > ASK_LIMITS.totalMax) {
+      full = true;
+      out.truncated = out.truncated.filter((id) => id !== el.id);
+      out.dropped.push(el.id);
+      continue;
+    }
+    total += chars(text);
+    out.context.push(text);
+    out.kept.push(el.id);
+  }
+  return out;
+}
+
 // src/photo.ts
 var PHOTO_TYPES = ["image/webp", "image/png", "image/jpeg", "image/avif"];
 var PHOTO_MAX_BYTES = 15 * 1024 * 1024;
@@ -2068,6 +2168,7 @@ var GameTier = /* @__PURE__ */ ((GameTier2) => {
   return GameTier2;
 })(GameTier || {});
 export {
+  ASK_LIMITS,
   ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
@@ -2089,6 +2190,7 @@ export {
   TokenResource,
   WORLD_FILE_MAX_BYTES,
   WORLD_FILE_MAX_ENTRIES,
+  buildAskContext,
   buildWorldIndex,
   detectKeyKind,
   elementColor,

package/package.json

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