@onlyworlds/sdk 4.29.0 → 4.30.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.30.1] — 2026-10-16
+
+### Fixed
+- **`changes()` and `changesAll()` hand back every cursor as a string**, as `OwChangesPage.cursor` has
+  always said. keel sends the cursor of a page at the head of the feed (an empty page, for any key but
+  a guest's) as a number, and it passed through as one: a walk of an up-to-date world returned
+  `{ cursor: 818 }`, so a cursor stored and compared as a string could miss. `changesHead()` already
+  did this. Found on production with a demo key.
+
+## [4.30.0] — 2026-10-16
+
+### Added
+- **A friend with only a link** (keel #353, D111):
+  - `redeemJoin(code, { name?, agentName? })`: redeems a join code that needs no account, at `POST /join`,
+    sending no credential whatever key the client holds. The answer's `kind` tells the two apart:
+    `OwPlayerJoined` (a read key, `ow_r_`, no PIN, and the Character the player reads as) or
+    `OwAgentJoined` (a seat's write key, secret and `.env` lines). Shown once; the code is spent, so a
+    lost answer means a new link. Every bad code is one 404.
+  - `createWorldLink(worldId, { reader: 'player', character? })`: a player link, guest only; `character`
+    is a Character's id or `new` (the default). `OwWorldLink.character` names it on the list.
+  - `player` joins the `kind` of `OwMe` and `OwMember`.
+- **A client with no key**: `apiKey` is optional. `new OwV2Client()` (or an empty key) has `keyKind: 'none'`
+  and can call `health`, `previewJoin` and `redeemJoin`, which is what a friend with only a link has; any
+  other call is a TypeError before anything is sent. Until now a key was required even for the routes
+  that send none.
+
 ## [4.29.0] — 2026-10-16
 
 ### Added

package/dist/index.d.ts

@@ -2171,7 +2171,8 @@ interface OwMe {
         name: string;
     };
     scope: 'read' | 'write';
-    kind: 'owner' | 'person' | 'agent';
+    /** `player`: a friend with no account, reading as a guest (keel #353). */
+    kind: 'owner' | 'person' | 'agent' | 'player';
     role: 'owner' | OwMemberRole;
     /** The membership id (what `created_by` holds for what this key creates), or null for the owner. */
     membership: string | null;
@@ -2185,7 +2186,7 @@ interface OwMe {
 interface OwMember {
     /** The membership id (what `created_by` holds), or null for the owner. */
     id: string | null;
-    kind: 'owner' | 'person' | 'agent';
+    kind: 'owner' | 'person' | 'agent' | 'player';
     role: 'owner' | OwMemberRole;
     /** The Character that is this member, or null. */
     character: string | null;
@@ -2209,8 +2210,8 @@ interface OwAllowance {
 }
 /** 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 & {});
+    /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. `player`: a friend with no account redeems it with redeemJoin for a read key (keel #353). */
+    reader: 'person' | 'agent' | 'player' | (string & {});
     world: {
         name: string;
         description: string | null;
@@ -2230,14 +2231,14 @@ interface OwJoinPreview {
 interface OwWorldLink {
     /** The link's id: revokeWorldLink takes it. */
     id: string;
-    /** `person`: accepted signed in, with acceptJoin. `agent`: redeemed by an AI agent at POST /join. */
-    reader: 'person' | 'agent';
+    /** `person`: accepted signed in, with acceptJoin. `agent`: redeemed by an AI agent at POST /join. `player`: redeemed with no account at POST /join, for a read key. */
+    reader: 'person' | 'agent' | 'player';
     role: OwMemberRole;
     /** The name the owner gave an agent link on the website, or empty. */
     label: string;
     /** The name the link is signed with, or empty (the invite line then reads "Someone"). */
     inviter_name: string;
-    /** Whether redeeming gives the agent a Character of its own. Always false on a person link. */
+    /** Whether redeeming gives the agent a Character of its own. Always false on a person link, always true on a player link. */
     with_character: boolean;
     /** The code's last four characters, to tell links apart. */
     last4: string;
@@ -2248,6 +2249,11 @@ interface OwWorldLink {
     /** 0 or 1: a link works once. */
     uses: number;
     status: 'pending' | 'used' | 'revoked' | 'expired';
+    /** 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). */
+    character?: {
+        id: string;
+        name: string | null;
+    } | null;
     [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. */
@@ -2259,6 +2265,58 @@ interface OwCreatedWorldLink extends OwWorldLink {
     /** The one line to send: who invites, to which world, and the link. */
     line: string;
 }
+/** POST /join, an agent's code: its seat, write key and secret, shown once (keel #212; `kind` since #353). */
+interface OwAgentJoined {
+    kind: 'agent';
+    world: {
+        id: string;
+        name: string;
+        description: string;
+        [k: string]: unknown;
+    };
+    seat: {
+        id: string;
+        role: OwMemberRole;
+        agent_name: string;
+        [k: string]: unknown;
+    };
+    with_character: boolean;
+    character: {
+        id: string;
+        name: string;
+    } | null;
+    /** The seat's write key (`API-Key`). */
+    key: string;
+    /** The seat's secret, sent as `API-Pin`. */
+    pin: string;
+    base_url: string;
+    /** The lines of a `.env` file for the agent. */
+    env: string;
+    next: string[];
+    members: Array<Record<string, unknown>>;
+    [k: string]: unknown;
+}
+/** POST /join, a player's code: a read key for a friend with no account, reading as a guest (keel #353). Shown once. */
+interface OwPlayerJoined {
+    kind: 'player';
+    /** A read key (`ow_r_`): no PIN, a player reads only. */
+    key: string;
+    world: {
+        id: string;
+        name: string;
+        description: string;
+        [k: string]: unknown;
+    };
+    /** The Character the player reads as. */
+    character: {
+        id: string;
+        name: string;
+    };
+    role: 'guest';
+    [k: string]: unknown;
+}
+/** POST /join's answer: tell the two apart by `kind`. */
+type OwJoined = OwAgentJoined | OwPlayerJoined;
 /** 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. */
@@ -2357,8 +2415,12 @@ interface ListParams {
     filter?: Record<string, string | number | boolean>;
 }
 interface OwClientConfig {
-    /** The key: an ow_w_ (write) or ow_r_ (read) world key, an ow_a_ account token (sent as a Bearer token, for the account routes), or a 10-digit legacy key. */
-    apiKey: string;
+    /**
+     * The key: an ow_w_ (write) or ow_r_ (read) world key, an ow_a_ account token (sent as a Bearer token, for the account routes), or a 10-digit legacy key.
+     * Leave it out for a client that holds none, such as a friend with only a link (since 4.30.0): it can call health,
+     * previewJoin and redeemJoin, and any other call is a TypeError before anything is sent.
+     */
+    apiKey?: string;
     /**
      * The PIN, needed for writes when the world has one, and for legacy-key reads of private worlds.
      * Prefixed keys read without a PIN. A string, not a number: '0123' !== 123.
@@ -2533,7 +2595,9 @@ type OwKeyKind =
 /** ow_a_ -- account Bearer token for /account/* routes; can mint world keys. */
  | 'account'
 /** Grandfathered 10-digit key. Needs PIN to read private worlds. */
- | 'legacy' | 'unknown';
+ | 'legacy' | 'unknown'
+/** No key: a client for the routes that send none (health, previewJoin, redeemJoin), as a friend with only a link has. */
+ | 'none';
 /** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
 declare function isDemoKey(key: string): boolean;
 declare function detectKeyKind(key: string): OwKeyKind;
@@ -2568,7 +2632,7 @@ declare class OwV2Client {
     private readonly apiPin;
     private readonly fetchImpl;
     private readonly agent;
-    constructor(config: OwClientConfig);
+    constructor(config?: OwClientConfig);
     /** GET /health -- unauthenticated liveness pulse. */
     health(): Promise<unknown>;
     /**
@@ -2671,6 +2735,8 @@ declare class OwV2Client {
      * view changed (a guest's, or its role): drop the cursor, walk from zero, and
      * replace the local copy rather than merging into it.
      * Citizenship: heaviest route on the platform; default page size is polite.
+     * keel sends the cursor of a page at the head as a number (an empty page, for anyone
+     * but a guest); it is handed back as a string, like every cursor here.
      */
     changes(opts?: {
         since?: string;
@@ -2769,6 +2835,21 @@ declare class OwV2Client {
      * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`.
      */
     previewJoin(code: string): Promise<OwJoinPreview>;
+    /**
+     * POST /join -- redeem a join code that needs no account: a player's (a friend reading as
+     * a guest, keel #353) or an AI agent's. Sends no credential, whatever key this client holds.
+     * 201 with `kind` telling the two answers apart: `player` gives a read key (`ow_r_`, no PIN)
+     * and the Character it reads as; `agent` gives a seat's write key, secret and `.env` lines.
+     * Both are shown once, and the code is spent: a lost answer cannot be replayed (the owner
+     * sees the row never used, and makes a new link). `name` (a player's, optional: the
+     * 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.
+     */
+    redeemJoin(code: string, opts?: {
+        name?: string;
+        agentName?: string;
+    }): Promise<OwJoined>;
     /**
      * 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`
@@ -2781,17 +2862,21 @@ declare class OwV2Client {
     /**
      * POST /account/worlds/{worldId}/links -- a new invite link for a world this client's
      * `ow_a_` token owns (keel C1): `reader` is required (`person`, accepted with acceptJoin;
-     * `agent`, redeemed at POST /join); `role` defaults to contributor, `days` (1, 7 or 30)
-     * to 7; `withCharacter` (agent links only) to true. 201 with the code, shown in this
+     * `agent`, redeemed at POST /join; `player`, a friend with no account, redeemed with
+     * redeemJoin for a read key, keel #353); `role` defaults to contributor (a player link is
+     * guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (agent links
+     * only) to true; `character` (player links only) a Character's id or `new` (the default):
+     * whoever opens the link first reads as it, until removed. 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.
      */
     createWorldLink(worldId: string, opts: {
-        reader: 'person' | 'agent';
+        reader: 'person' | 'agent' | 'player';
         role?: OwMemberRole;
         days?: 1 | 7 | 30;
         inviterName?: string;
         withCharacter?: boolean;
+        character?: string;
     }): Promise<OwCreatedWorldLink>;
     /**
      * GET /account/worlds/{worldId}/links -- the world's invite links, without their codes:
@@ -3842,4 +3927,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 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 };
+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 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 OwElement, type OwElementBase, type OwErrorBody, 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 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

@@ -249,11 +249,10 @@ var DEFAULT_BASE_URL = "https://www.onlyworlds.com/api/v2";
 var DEFAULT_PAGE_SIZE = 100;
 var DEFAULT_CHANGES_PAGE_SIZE = 100;
 var OwV2Client = class {
-  constructor(config) {
-    if (!config.apiKey) throw new Error("OwV2Client: apiKey is required");
-    this.apiKey = config.apiKey;
+  constructor(config = {}) {
+    this.apiKey = config.apiKey ?? "";
     this.apiPin = config.apiPin || void 0;
-    this.keyKind = detectKeyKind(config.apiKey);
+    this.keyKind = config.apiKey ? detectKeyKind(config.apiKey) : "none";
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE;
     this.changesPageSize = config.changesPageSize ?? DEFAULT_CHANGES_PAGE_SIZE;
@@ -432,10 +431,13 @@ var OwV2Client = class {
    * view changed (a guest's, or its role): drop the cursor, walk from zero, and
    * replace the local copy rather than merging into it.
    * Citizenship: heaviest route on the platform; default page size is polite.
+   * keel sends the cursor of a page at the head as a number (an empty page, for anyone
+   * but a guest); it is handed back as a string, like every cursor here.
    */
   async changes(opts = {}) {
     const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
-    return this.request("GET", "/changes/", { query });
+    const page = await this.request("GET", "/changes/", { query });
+    return { ...page, cursor: String(page.cursor) };
   }
   /**
    * GET /changes?head=true -- where the feed is now, without a page: no element is read.
@@ -569,6 +571,23 @@ var OwV2Client = class {
   async previewJoin(code) {
     return this.request("POST", "/join/preview", { auth: false, body: { code } });
   }
+  /**
+   * POST /join -- redeem a join code that needs no account: a player's (a friend reading as
+   * a guest, keel #353) or an AI agent's. Sends no credential, whatever key this client holds.
+   * 201 with `kind` telling the two answers apart: `player` gives a read key (`ow_r_`, no PIN)
+   * and the Character it reads as; `agent` gives a seat's write key, secret and `.env` lines.
+   * Both are shown once, and the code is spent: a lost answer cannot be replayed (the owner
+   * sees the row never used, and makes a new link). `name` (a player's, optional: the
+   * 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.
+   */
+  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;
+    return this.request("POST", "/join", { auth: false, body });
+  }
   /**
    * 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`
@@ -586,8 +605,11 @@ var OwV2Client = class {
   /**
    * POST /account/worlds/{worldId}/links -- a new invite link for a world this client's
    * `ow_a_` token owns (keel C1): `reader` is required (`person`, accepted with acceptJoin;
-   * `agent`, redeemed at POST /join); `role` defaults to contributor, `days` (1, 7 or 30)
-   * to 7; `withCharacter` (agent links only) to true. 201 with the code, shown in this
+   * `agent`, redeemed at POST /join; `player`, a friend with no account, redeemed with
+   * redeemJoin for a read key, keel #353); `role` defaults to contributor (a player link is
+   * guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (agent links
+   * only) to true; `character` (player links only) a Character's id or `new` (the default):
+   * whoever opens the link first reads as it, until removed. 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.
    */
@@ -600,6 +622,7 @@ var OwV2Client = class {
     if (opts.days !== void 0) body.days = opts.days;
     if (opts.inviterName !== void 0) body.inviter_name = opts.inviterName;
     if (opts.withCharacter !== void 0) body.with_character = opts.withCharacter;
+    if (opts.character !== void 0) body.character = opts.character;
     return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/links`, { body });
   }
   /**
@@ -743,6 +766,9 @@ var OwV2Client = class {
     if (opts.ifMatch !== void 0 && !(Number.isInteger(opts.ifMatch) && opts.ifMatch >= 0)) {
       throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
     }
+    if (opts.auth !== false && this.keyKind === "none") {
+      throw new TypeError(`${method} ${path} needs a key, and this client holds none: without one, only health, previewJoin and redeemJoin work`);
+    }
     const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
     const headers = {};
     if (opts.auth !== false) {

package/package.json

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