@onlyworlds/sdk 4.58.0 → 4.60.0

package/AGENTS.md

@@ -64,8 +64,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Allowance (since 4.21.0, account token): `account.allowance()` reads the daily AI allowance
   without spending: `{ token_rating, tokens_used_today, tokens_remaining, resets_at }`.
 - Who am I (since 4.22.0, a world key): `client.me()` is `{ world, scope, kind, role,
-  membership, character }` (`membership` is what `created_by` holds for what you create; null
-  for the owner); `client.members()` is the roster's rows. An account token is a TypeError.
+  membership, character, front_door }` (`membership` is what `created_by` holds for what you
+  create; null for the owner); `front_door` (since 4.60.0, keel #558) names who answers for your
+  seat (`sponsor`, `sponsor_character`), your Character, and the world's Charter with up to five
+  skill Objects: an agent reads `charter` first. `client.members()` is the roster's rows. An
+  account token is a TypeError.
 - Signing in (no key needed): `new OwV2Client().signInWithPassword({ email, password,
   tokenName })` (or `username`) mints an `ow_a_` account token named for the device and ends
   the sign-in session; only the token comes back. Refusals: `OwSignInError` with `reason`
@@ -148,4 +151,5 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 
 **Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
 primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
-test credentials against real data.
+test credentials against real data. A configured `apiPin` is sent only where keel checks it:
+on writes, on `me()`, and on every request of a 10-digit legacy key; other reads go without it.

package/CHANGELOG.md

@@ -5,6 +5,19 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.60.0] - 2026-10-22
+
+### Added
+
+- **`OwFrontDoor`, and `front_door` on `OwMe` and `OwAgentJoined`** (keel #558, D152, live 2026-10-22 20:1x). `me()`, `setMyCharacter()` and an agent's `redeemJoin()` answer carry the world's front door for the key: `sponsor` (`{id, kind, name}` of the person who answers for a seat, or null), `sponsor_character`, `my_character`, `charter` (the world's Charter, every member's to read: read it first) and `charter_skill` (up to five Objects the Charter names). Every id is one the key may read; anything hidden is null or left out. Types only: the client already passed the body through. Required on both types, as keel's document declares it; a hand-built `OwMe` in a consumer's test needs the field.
+
+## [4.59.0] - 2026-10-22
+
+### Changed
+
+- **`API-Pin` is sent only where keel checks it** (Skeld's ruling, OW Keel h29 #10663). keel verifies a PIN wherever one is sent (argon2, 64 MiB each), and on 2026-10-22 scripts reading with the PIN OOM-killed staging on a cold cache after a restart. The client used to send a configured `apiPin` on every request. It now sends it on every request whose method is not GET (every write: elements, links, bulk, adopt, hide and unhide, media and file tickets, seats, world links, proposals, `setMyCharacter`, `mintWorldKey`, `patchWorld`, and any route added later), on `GET /me` (`me()`, the connection test: keel checks a PIN there when sent, keel #314, D93), and on every request of a 10-digit legacy key (v1 parity, keel #421: such a key needs the PIN on reads of a world with a PIN). Any other read from an `ow_w_`, `ow_r_` or member key goes without it; an account token never sent it and still does not. The rule is derived in `request()` from the method and path, so a raw `request()` call follows it too. No API changed.
+- Tests: `test/api-pin.test.mjs`, five, on a recorded fetch: eight reads, `me()` and ten writes across POST, PATCH, PUT and DELETE, for an `ow_w_` key with a PIN, a legacy key with a PIN, an `ow_r_` key with none and an account token with one configured; and raw `request()` GETs to other paths, `/me` and other methods. Two existing tests that expected the PIN on a GET now expect none. Mutants: the PIN on every request again fails four tests; without the `/me` clause, three; without the legacy clause, one.
+
 ## [4.58.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -165,7 +165,7 @@ await account.revokeWorldLink(worldId, made.id);
 Once in, a world key can ask who it is and who else is there (since 4.22.0):
 
 ```typescript
-const me = await client.me();           // { world, scope, kind, role, membership, character }
+const me = await client.me();           // { world, scope, kind, role, membership, character, front_door }: front_door.charter is the house rules, read first
 const roster = await client.members();  // [{ id, kind, role, character, status }], the owner's id is null
 ```
 

package/dist/index.d.ts

@@ -2420,8 +2420,36 @@ interface OwMe {
     character: string | null;
     /** Agent seats only: the agent's name. */
     name?: string;
+    /** Who you are here, who answers for you, and the house rules (keel #558). */
+    front_door: OwFrontDoor;
     [k: string]: unknown;
 }
+/**
+ * A world's front door for one key (keel #558, D152): on `GET /me`, `PUT /me/character` and an
+ * agent's `POST /join` answer. Every id is one the key may read; anything hidden from it, or
+ * outside what its role sees, is null or left out. Read `charter` first.
+ */
+interface OwFrontDoor {
+    /**
+     * The person who answers for this seat (an AI or a player seat): `id` their membership id
+     * (null for the world's owner), `kind`, and `name` their Character's name (null when they play
+     * none this key can read). Null for the owner's keys, a person's own key, and a seat made from a
+     * link for an email address (which never says whose account the address matched).
+     */
+    sponsor: {
+        id: string | null;
+        kind: 'owner' | 'person';
+        name: string | null;
+    } | null;
+    /** The sponsor's Character, the one to address a message to, or null. */
+    sponsor_character: string | null;
+    /** Your own Character (the owner's: the world's `owner_character`), or null. */
+    my_character: string | null;
+    /** The world's Charter: the newest Law with supertype Charter made by the owner or a co-builder, or null. Every member may read it. */
+    charter: string | null;
+    /** The Objects the Charter's description names (by `ow://` link or id), in the order written, at most five; empty when none. */
+    charter_skill: string[];
+}
 /** One row of GET /members, the world's roster. */
 interface OwMember {
     /** The membership id (what `created_by` holds), or null for the owner. */
@@ -2558,6 +2586,8 @@ interface OwAgentJoined {
     env: string;
     next: string[];
     members: Array<Record<string, unknown>>;
+    /** The world's front door for the new seat: its sponsor, its Character, the Charter to read first (keel #558). */
+    front_door: OwFrontDoor;
     [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. */
@@ -2924,8 +2954,11 @@ interface OwClientConfig {
      */
     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.
+     * The PIN (or an agent seat's `ow_s_` secret), needed for writes when the world has one, and for
+     * legacy-key reads of a world with a PIN. Sent as `API-Pin` only where keel checks it: on every
+     * write (any method but GET), on GET /me (me(), the connection test), and on every request of a
+     * 10-digit legacy key. A prefixed key's other reads go without it, and an account token never
+     * sends it. A string, not a number: '0123' !== 123.
      */
     apiPin?: string;
     /** The API's base URL, default https://www.onlyworlds.com/api/v2. */
@@ -5127,4 +5160,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 OwAccountWorld, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwHiddenRow, 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, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, 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 OwAccountWorld, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, 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, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -1725,7 +1725,9 @@ var OwV2Client = class {
         headers["Authorization"] = `Bearer ${this.apiKey}`;
       } else {
         headers["API-Key"] = this.apiKey;
-        if (this.apiPin) headers["API-Pin"] = this.apiPin;
+        const read = method.toUpperCase() === "GET";
+        const me = path === "/me/" || path === "/me";
+        if (this.apiPin && (!read || me || this.keyKind === "legacy")) headers["API-Pin"] = this.apiPin;
       }
     }
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";

package/package.json

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