@onlyworlds/sdk 4.21.0 → 4.23.0

package/AGENTS.md

@@ -54,6 +54,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   allowance as ask.
 - 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.
 - 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.

package/CHANGELOG.md

@@ -5,6 +5,37 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.23.0] — 2026-10-14
+
+### Deprecated
+- **`TokenResource.consume()`, `getAccessKey()`, `revokeSession()`, `revokeAllSessions()`**: keel
+  serves none of these routes (each answers 404 `not_found` on production; `accounts/token_api.py`
+  mounts only `status/` and `encryption-info/`). Spending is server-side, in the route that does the
+  work (the Council's acts through keel's council proxy, keel #274, Skeld's ruling h37 #4632), and
+  `OwV2Client.allowance()` reads the token rating. They stay callable and leave in 5.0. A 404 from
+  any token route now says what keel serves instead of "an older server". Found by Assembly's wire
+  gate, which until now never drove this class (its routes are not in keel's document).
+
+### Changed
+- README and docs: "token rating" is the one word for the account's daily budget (the Captain,
+  h37 #4642, OW Infra #273). Names in the API (`allowance()`, `/account/allowance`) are unchanged.
+
+## [4.22.0] — 2026-10-14
+
+### Added
+- **`client.me()` and `client.members()`**: GET /me (who this world key is: world, scope, kind,
+  role, membership id, Character) and GET /members (the roster's rows, unwrapped from `{ data }`).
+  Lantern reads a player's role from /me by hand today. Types `OwMe`, `OwMember`, typed from
+  keel's declared schemas and held to them by Assembly's wire gate. An account token is a
+  TypeError before sending; the tests fail with that guard removed, or with the rows left
+  wrapped.
+
+### Changed
+- The calendar kernel is the SDK's own: Atlas 245aad3 deleted its `core/calendar.ts` and imports
+  this one (Temper, h37 #4472), so the copy record (`src/calendar/SOURCES.json`) and the re-copy
+  script (`codegen/atlas-calendar.mjs`) are gone. A kernel change is an SDK release now. No code
+  change.
+
 ## [4.21.0] — 2026-10-14
 
 ### Added

package/README.md

@@ -121,6 +121,15 @@ const membership = await account.acceptJoin(code); // account = a client with an
 
 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.
 
+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 roster = await client.members();  // [{ id, kind, role, character, status }], the owner's id is null
+```
+
+`me.membership` is what `created_by` holds on the elements this key creates; `me.role` decides what it may change.
+
 ## Sync
 
 ```typescript
@@ -182,7 +191,7 @@ const { rows, not_proposed } = await account.sort({ worldId, notes: ['Mira moved
 // rows: make (a new element), add_to (text for a field), link (one element to another), ask (which one?)
 ```
 
-Asking and sorting spend tokens from the account's daily AI allowance, the same meter the Council uses. Each answer carries `tokens_remaining` and `token_rating`; `allowance()` reads the meter without spending anything (since 4.21.0):
+Asking and sorting spend tokens from the account's token rating, its daily budget, the same meter the Council uses. Each answer carries `tokens_remaining` and `token_rating`; `allowance()` reads the meter without spending anything (since 4.21.0):
 
 ```typescript
 const { token_rating, tokens_remaining, resets_at } = await account.allowance(); // resets_at: the next midnight UTC
@@ -245,7 +254,7 @@ The four colour families (agents, world, abstract, temporal) are checked for col
 
 ## Tokens
 
-The account's token allowance and ratings, which some OnlyWorlds tools use.
+The account's token rating, which some OnlyWorlds tools use. `getStatus()` and `getEncryptionInfo()` are what keel still serves under `/tokens/`; `consume()`, `getAccessKey()` and the two session revokes are deprecated (keel answers 404) and leave in 5.0. To read the token rating, prefer `account.allowance()` above.
 
 ```typescript
 import { TokenResource } from '@onlyworlds/sdk';

package/dist/index.d.ts

@@ -2104,6 +2104,37 @@ interface OwSortAnswer {
     token_rating: number;
     [k: string]: unknown;
 }
+/** GET /me: who this world key is. */
+interface OwMe {
+    world: {
+        id: string;
+        name: string;
+    };
+    scope: 'read' | 'write';
+    kind: 'owner' | 'person' | 'agent';
+    role: 'owner' | OwMemberRole;
+    /** The membership id (what `created_by` holds for what this key creates), or null for the owner. */
+    membership: string | null;
+    /** The member's Character, or null. */
+    character: string | null;
+    /** Agent seats only: the agent's name. */
+    name?: string;
+    [k: string]: unknown;
+}
+/** One row of GET /members, the world's roster. */
+interface OwMember {
+    /** The membership id (what `created_by` holds), or null for the owner. */
+    id: string | null;
+    kind: 'owner' | 'person' | 'agent';
+    role: 'owner' | OwMemberRole;
+    /** The Character that is this member, or null. */
+    character: string | null;
+    /** `removed` rows stay, so their elements keep `created_by`. */
+    status: 'active' | 'removed';
+    /** Agent rows only: the agent's name. */
+    name?: string;
+    [k: string]: unknown;
+}
 /** GET /account/allowance: the account's daily AI allowance (keel 872431f, 2026-10-14). */
 interface OwAllowance {
     /** The account's daily allowance in tokens. */
@@ -2395,6 +2426,19 @@ declare class OwV2Client {
     getWorld(): Promise<OwWorldMeta>;
     /** PATCH /world -- partial world-meta update. */
     patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
+    /**
+     * GET /me -- who this world key is: the world, read or write scope, the kind (owner,
+     * person, agent), the role, the membership id (what `created_by` holds for what this key
+     * creates; null for the owner) and the member's Character. A world key's call; an account
+     * token is a TypeError before sending.
+     */
+    me(): Promise<OwMe>;
+    /**
+     * GET /members -- the world's roster: each member's id (null for the owner), kind, role,
+     * Character and status (`removed` rows stay, so their elements keep `created_by`). Returns
+     * the rows; keel sends them as `{ data }` with no paging. A world key's call.
+     */
+    members(): Promise<OwMember[]>;
     /** GET /{type}/ -- one cursor page. */
     list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
     /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
@@ -3212,11 +3256,12 @@ declare function parseDate(cfg: CalendarConfig, input: string, opts?: ParseOptio
 declare function isParseError(r: ParseResult | ParseError): r is ParseError;
 
 /**
- * World calendars: Atlas's calendar kernel, and which calendars a world holds.
+ * World calendars: the calendar kernel, and which calendars a world holds.
  *
- * `calendar.ts` beside this file is Atlas's `src/core/calendar.ts`, byte for byte
- * (Forge/tools/atlas; recorded in `SOURCES.json`, checked with Assembly's copy-drift).
- * Never edit it here: change Atlas's, then copy and re-record. This file adapts Atlas's
+ * `calendar.ts` beside this file came from Atlas's `src/core/calendar.ts` in 4.20.0, and is
+ * the one copy since Atlas 245aad3 deleted its own and imports this one (Temper, h37 #4472):
+ * a kernel change is an SDK release, and Atlas's 48 kernel tests run against it there too.
+ * Its contract is still Atlas's calendar design, §5 and §5b. This file adapts Atlas's
  * `src/core/calendar-lens.ts` (readCalendarValue, worldCalendars, resolveCalendarLens) to
  * any element shape, since the SDK has no Atlas `Element`.
  *
@@ -3393,6 +3438,12 @@ declare enum GameTier {
  * `OwV2Client` (its `request()` is public since 4.0): `new TokenResource(client)`.
  * Wire ruling (2026-07-23): keel keeps the /tokens/* economy long-term
  * (Tangle ratings write it, Council voting reads it) — port, don't delete.
+ * Since then keel mounts only `status/` and `encryption-info/` under /tokens/
+ * (`accounts/token_api.py`; consume, access-key and both revokes answer 404 on
+ * production, 2026-10-14), and spending moved server-side: the Council spends
+ * through keel's council proxy (keel #274, Skeld's ruling h37 #4632), and
+ * `OwV2Client.allowance()` reads the token rating. The four dead methods are
+ * deprecated in 4.23.0 and leave in 5.0.
  */
 interface TokenTransport {
     request<T>(method: string, path: string, opts?: {
@@ -3429,9 +3480,9 @@ declare class TokenResource {
     private client;
     constructor(client: TokenTransport);
     /**
-     * All token routes go through here: a 404 on /tokens/* almost always means
-     * the SERVER predates the v2 token mount (keel >= 2026-07-23, e181689) —
-     * not "user has no tokens". Annotate so the failure reads correctly.
+     * All token routes go through here: a 404 on /tokens/* means keel does not
+     * serve that route, not "user has no tokens". Annotate so the failure reads
+     * correctly.
      */
     private req;
     /**
@@ -3453,6 +3504,10 @@ declare class TokenResource {
     /**
      * Consume tokens for service usage
      *
+     * @deprecated keel serves no consume route (404 on production since 2026-10;
+     * no client decides what its act costs, Skeld's ruling, keel #274): spending
+     * happens server-side in the route that does the work. Removed in 5.0.
+     *
      * Reports token consumption to track daily usage. Allows consumption even if
      * exceeds available tokens (tracks as debt), but warns via error field.
      * Matches base-tool's reportUsage() pattern.
@@ -3482,6 +3537,10 @@ declare class TokenResource {
     /**
      * Get encrypted OpenAI API key (advanced use case)
      *
+     * @deprecated keel serves no access-key route (404 on production since
+     * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask()` and
+     * `sort()`. Removed in 5.0.
+     *
      * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
      * Returns encrypted key that must be decrypted client-side using Fernet.
      *
@@ -3509,6 +3568,9 @@ declare class TokenResource {
     /**
      * Revoke a specific token session
      *
+     * @deprecated keel serves no revoke-session route (404 on production since
+     * 2026-10); sessions came from getAccessKey(), which is gone too. Removed in 5.0.
+     *
      * Invalidates the session ID obtained from getAccessKey().
      * Use when cleaning up or on logout.
      *
@@ -3523,6 +3585,9 @@ declare class TokenResource {
     /**
      * Revoke all active sessions (emergency use)
      *
+     * @deprecated keel serves no revoke-all-sessions route (404 on production
+     * since 2026-10). Removed in 5.0.
+     *
      * Invalidates all token sessions for the authenticated user.
      * Use for security cleanup or when sessions are stuck.
      *
@@ -3552,4 +3617,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { 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 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, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, 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 OwWorldMeta, 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, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { 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 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 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 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 OwWorldMeta, 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, 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

@@ -212,6 +212,31 @@ var OwV2Client = class {
   async patchWorld(partial) {
     return this.request("PATCH", "/world/", { body: sanitizePayload(partial) });
   }
+  // -- Who am I, and who is here ---------------------------------------------
+  /**
+   * GET /me -- who this world key is: the world, read or write scope, the kind (owner,
+   * person, agent), the role, the membership id (what `created_by` holds for what this key
+   * creates; null for the owner) and the member's Character. A world key's call; an account
+   * token is a TypeError before sending.
+   */
+  async me() {
+    if (this.keyKind === "account") {
+      throw new TypeError("me needs a world key: an account token is not a member of one world");
+    }
+    return this.request("GET", "/me/");
+  }
+  /**
+   * GET /members -- the world's roster: each member's id (null for the owner), kind, role,
+   * Character and status (`removed` rows stay, so their elements keep `created_by`). Returns
+   * the rows; keel sends them as `{ data }` with no paging. A world key's call.
+   */
+  async members() {
+    if (this.keyKind === "account") {
+      throw new TypeError("members needs a world key: an account token is not a member of one world");
+    }
+    const page = await this.request("GET", "/members/");
+    return page.data ?? [];
+  }
   // -- Element CRUD --------------------------------------------------------
   /** GET /{type}/ -- one cursor page. */
   async list(type, params = {}) {
@@ -2602,16 +2627,16 @@ var TokenResource = class {
     this.client = client;
   }
   /**
-   * All token routes go through here: a 404 on /tokens/* almost always means
-   * the SERVER predates the v2 token mount (keel >= 2026-07-23, e181689) —
-   * not "user has no tokens". Annotate so the failure reads correctly.
+   * All token routes go through here: a 404 on /tokens/* means keel does not
+   * serve that route, not "user has no tokens". Annotate so the failure reads
+   * correctly.
    */
   async req(method, path, opts) {
     try {
       return await this.client.request(method, path, opts);
     } catch (err) {
       if (err && typeof err === "object" && err.status === 404) {
-        err.message += " [token routes require keel >= 2026-07-23 (e181689) on /api/v2 \u2014 a 404 here usually means an older server, not zero tokens]";
+        err.message += " [keel serves only /tokens/status/ and /tokens/encryption-info/; this method is deprecated (4.23.0). The token rating: OwV2Client.allowance()]";
       }
       throw err;
     }
@@ -2637,6 +2662,10 @@ var TokenResource = class {
   /**
    * Consume tokens for service usage
    *
+   * @deprecated keel serves no consume route (404 on production since 2026-10;
+   * no client decides what its act costs, Skeld's ruling, keel #274): spending
+   * happens server-side in the route that does the work. Removed in 5.0.
+   *
    * Reports token consumption to track daily usage. Allows consumption even if
    * exceeds available tokens (tracks as debt), but warns via error field.
    * Matches base-tool's reportUsage() pattern.
@@ -2675,6 +2704,10 @@ var TokenResource = class {
   /**
    * Get encrypted OpenAI API key (advanced use case)
    *
+   * @deprecated keel serves no access-key route (404 on production since
+   * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask()` and
+   * `sort()`. Removed in 5.0.
+   *
    * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
    * Returns encrypted key that must be decrypted client-side using Fernet.
    *
@@ -2704,6 +2737,9 @@ var TokenResource = class {
   /**
    * Revoke a specific token session
    *
+   * @deprecated keel serves no revoke-session route (404 on production since
+   * 2026-10); sessions came from getAccessKey(), which is gone too. Removed in 5.0.
+   *
    * Invalidates the session ID obtained from getAccessKey().
    * Use when cleaning up or on logout.
    *
@@ -2723,6 +2759,9 @@ var TokenResource = class {
   /**
    * Revoke all active sessions (emergency use)
    *
+   * @deprecated keel serves no revoke-all-sessions route (404 on production
+   * since 2026-10). Removed in 5.0.
+   *
    * Invalidates all token sessions for the authenticated user.
    * Use for security cleanup or when sessions are stuck.
    *

package/package.json

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