@onlyworlds/sdk 4.20.0 → 4.22.0

package/AGENTS.md

@@ -50,7 +50,13 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Sort (since 4.18.0, account token): `account.sort({ worldId, notes, slice })` turns unsorted
   notes (text, or a picture already uploaded into the world) into rows to review: `make`,
   `add_to`, `link`, `ask`, plus `not_proposed` with reasons. Ids come only from your `slice`
-  (up to 100 elements your own lookup found); nothing is written. Counts as one ask.
+  (up to 100 elements your own lookup found); nothing is written. Spends from the same
+  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,35 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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
+- **`client.allowance()`**: GET /account/allowance (keel 872431f, Skeld h37 #4308), the
+  account's daily AI allowance read without spending: `token_rating`, `tokens_used_today`,
+  `tokens_remaining`, `resets_at` (the next midnight UTC). Account token only, like ask and
+  sort. Type `OwAllowance`, held by Assembly's wire gate to the route's declared schema, as
+  `OwAskAnswer`, `OwSortAnswer` and `OwJoinPreview` now are to theirs.
+
+### Fixed
+- README and AGENTS.md no longer say a sort counts as one ask: since keel a6244db both spend
+  tokens from the allowance.
+
 ## [4.20.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
@@ -174,7 +183,7 @@ const reply = await account.ask({ worldId, question, context }); // account: a c
 reply.answer;                                            // from those elements only, or "The world doesn't say."
 ```
 
-The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts. A sort counts as one question.
+The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts.
 
 ```typescript
 const slice = hits.slice(0, 100).map(({ element: e }) => ({ id: e.id, type: e.type, name: e.name }));
@@ -182,6 +191,12 @@ 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):
+
+```typescript
+const { token_rating, tokens_remaining, resets_at } = await account.allowance(); // resets_at: the next midnight UTC
+```
+
 ## World files
 
 A world file is one `.zip` holding a whole world folder (`world.json` and `elements/<type>/*.json`, as Atlas keeps a world on disk), the way Atlas downloads and opens one. It needs no account and works in the browser and in Node.

package/dist/index.d.ts

@@ -2104,6 +2104,49 @@ 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. */
+    token_rating: number;
+    /** Tokens spent today (UTC); may pass the rating by the size of the last call. */
+    tokens_used_today: number;
+    /** Tokens left today, never below 0. */
+    tokens_remaining: number;
+    /** When the allowance resets: the next midnight UTC (ISO 8601). */
+    resets_at: string;
+    [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. */
@@ -2383,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. */
@@ -2583,7 +2639,7 @@ declare class OwV2Client {
      * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
      * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
      * row is from the slice; keel moves any other row to `not_proposed` with its reason.
-     * A sort counts as one ask: the same account token, allowance and refusals as ask. 422
+     * The same account token, allowance (it spends the tokens it uses) and refusals as ask. 422
      * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
      * only), at most four pictures, each uploaded into this world; slice up to 100, names up
      * to 200 characters, anchors up to 120.
@@ -2593,6 +2649,12 @@ declare class OwV2Client {
         notes: OwSortNote[];
         slice: OwSortRef[];
     }): Promise<OwSortAnswer>;
+    /**
+     * GET /account/allowance -- the account's daily AI allowance, the one meter ask, sort and
+     * the Council spend from (keel 872431f): the rating, what is used and left today, and
+     * when it resets (the next midnight UTC). Spends nothing. Needs the client's `ow_a_` token.
+     */
+    allowance(): Promise<OwAllowance>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -3194,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`.
  *
@@ -3534,4 +3597,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, 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 = {}) {
@@ -500,7 +525,7 @@ var OwV2Client = class {
    * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
    * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
    * row is from the slice; keel moves any other row to `not_proposed` with its reason.
-   * A sort counts as one ask: the same account token, allowance and refusals as ask. 422
+   * The same account token, allowance (it spends the tokens it uses) and refusals as ask. 422
    * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
    * only), at most four pictures, each uploaded into this world; slice up to 100, names up
    * to 200 characters, anchors up to 120.
@@ -513,6 +538,17 @@ var OwV2Client = class {
       body: { world_id: req.worldId, notes: req.notes, slice: req.slice }
     });
   }
+  /**
+   * GET /account/allowance -- the account's daily AI allowance, the one meter ask, sort and
+   * the Council spend from (keel 872431f): the rating, what is used and left today, and
+   * when it resets (the next midnight UTC). Spends nothing. Needs the client's `ow_a_` token.
+   */
+  async allowance() {
+    if (this.keyKind !== "account") {
+      throw new TypeError("allowance needs an account token (ow_a_): the allowance is per account");
+    }
+    return this.request("GET", "/account/allowance");
+  }
   // -- 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.20.0",
+  "version": "4.22.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {