@onlyworlds/sdk 4.0.0-alpha.0 → 4.0.0-alpha.1

package/AGENTS.md

@@ -1,34 +1,34 @@
-# For AI agents using @onlyworlds/sdk
-
-**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
-every type, every field with its meaning, link directions, families, icons, display sections.
-It is generated from the same canonical YAML as the types, so it cannot drift.
-
-**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
-plus the canonical constants (element types, icons, colour families, field schema).
-OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
-
-**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
-interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
-against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is frozen
-legacy — do not build new work on it.
-
-**SDK vs MCP server — pick correctly**:
-- Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
-  responses, far cheaper than tool-schema reasoning.
-- Live exploration of a user's world from a chat/agent context → the **MCP server** at
-  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools).
-
-**Wire facts that bite** (full details in README):
-- Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
-- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
-- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
-- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
-- Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
-  unknown unprefixed fields 422.
-- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
-  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
-
-**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.
+# For AI agents using @onlyworlds/sdk
+
+**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
+every type, every field with its meaning, link directions, families, icons, display sections.
+It is generated from the same canonical YAML as the types, so it cannot drift.
+
+**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
+plus the canonical constants (element types, icons, colour families, field schema).
+OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
+
+**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
+interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
+against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is frozen
+legacy — do not build new work on it.
+
+**SDK vs MCP server — pick correctly**:
+- Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
+  responses, far cheaper than tool-schema reasoning.
+- Live exploration of a user's world from a chat/agent context → the **MCP server** at
+  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools).
+
+**Wire facts that bite** (full details in README):
+- Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
+- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
+- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
+- Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
+  unknown unprefixed fields 422.
+- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
+  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
+
+**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.

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
 earlier history lives in git log only.
 
-## [Unreleased — 4.0.0] (branch `v4`)
+## [4.0.0] — 2026-07-23
 
 **v2-native only.** See `docs/migrating-3-to-4.md`. 3.x stays published forever for
 pinned consumers.
@@ -40,10 +40,27 @@ pinned consumers.
 - README rewritten v2-native (v1 sections, branded types, and the encrypted-key
   walkthrough removed; bulk partial-failure and idempotency-key hygiene promoted).
 
-### Planned before release (RFC-001 gates)
-- Skeld's live wire-log v1-traffic query (gate 3). Alpha publishes to the `alpha`
-  dist-tag only — never `latest`. **No `npm deprecate` on 3.x** (amended per landscape
-  research — 3.x stays plainly supported; README framing carries the message).
+### alpha.1 — consumer-pin fixes (Temper's atlas review, same night)
+- **`parseEnvelope` → `parseErrorEnvelope`** (it parses the platform *error* envelope;
+  renamed before the 4.0 name freeze to avoid collision with the world-export envelope).
+- The never-whitelist LAW now lives as a comment on `READ_ONLY_FIELDS` itself.
+- Stale v1 example in the shipped d.ts fixed (TokenResource JSDoc).
+
+### Release gates — ALL GREEN (2026-07-23 night)
+- **Gate 3 (wire-log v1-traffic query, Skeld)**: GREEN — no unknown v1-SDK consumer on
+  the wire; observed v1 traffic is pinned deployed builds (council proxy, legacy plugin
+  walks) that an npm major cannot touch. The v1 API dialect stays served regardless.
+- **`/api/v2/tokens/` live on prod + staging** (keel `e181689`; three-base byte
+  agreement test-pinned). `TokenResource` annotates a 404 on token routes as
+  "older server", not "no tokens". Requirement noted in the migration guide.
+- **`ONLYWORLDS_VERSION` now GENERATED** from canonical's `VERSION` file (carried
+  into keel `schema/` by the refresh script, keel `492168c`) — the last hand-synced
+  constant is dead. Consumer soak: Temper pinned the alpha against atlas's full
+  static surface — strict-clean compile, correct runtime, package shape approved.
+- **No `npm deprecate` on 3.x** (landscape research; 3.x stays plainly supported).
+- 4.x wishlist: account client (list/mint/create — atlas first consumer), world-export
+  envelope reader (§8c), per-status error classes, richer codegen JSDoc, retry/backoff
+  parity audit, FIELD_SCHEMA generation with `required:` from YAML.
 
 ## [3.1.0] — 2026-07-23
 

package/README.md

@@ -1,144 +1,144 @@
-# OnlyWorlds TypeScript SDK
-
-[![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-The canonical typed client for the [OnlyWorlds](https://onlyworlds.github.io) v2 API, plus the
-canonical constants (element types, icons, colour families, field schema) — generated from the
-same schema source the server runs on.
-
-**4.x is v2-native and ESM-only (Node 18+).** If you need the legacy v1 API dialect
-(`OnlyWorldsClient`) or CommonJS `require()`, stay on 3.x — it remains published and the v1 API
-remains served. See [docs/migrating-3-to-4.md](docs/migrating-3-to-4.md).
-
-## Installation
-
-```bash
-npm install @onlyworlds/sdk
-```
-
-## Quick Start
-
-```typescript
-import { OwV2Client } from '@onlyworlds/sdk';
-
-const client = new OwV2Client({ apiKey: 'ow_r_your_key' }); // read-only key: that's all you need
-const page = await client.list('character');                 // { data, has_more, next_cursor }
-```
-
-Key kinds: `ow_w_` write / `ow_r_` read-only (no PIN — the "give this to your players" key) /
-`ow_a_` account Bearer / 10-digit legacy. Writes on a PIN-protected world also pass `apiPin`.
-Demo keys `0000000000`–`0000000009` read real sample worlds.
-
-## The full round-trip
-
-```typescript
-const writer = new OwV2Client({ apiKey: 'ow_w_your_key', apiPin: '1234' });
-
-// v2 dialect rules, worth internalizing once:
-// - link fields use ONE bare name both directions (no _ids suffix — that's v1)
-// - NEVER send a "world" field (identity comes from the key; the client strips it anyway)
-const location = await writer.create('location', {
-  name: 'Dragon Peak',
-  description: 'A treacherous mountain peak where dragons nest',
-}); // id minted client-side when omitted (retries stay idempotent)
-
-const dragon = await writer.create('creature', {
-  name: 'Vorrath the Ember-Scaled',
-  location: location.id,            // single link: UUID (or null)
-});
-
-const fetched = await writer.get('creature', dragon.id);
-// fetched.location === location.id — reads the way it writes
-
-// PATCH is destructive on sent fields; arrays replace wholesale
-await writer.patch('location', location.id, { supertype: 'Mountain' });
-
-// For relationships, use the atomic link merge — returns the full updated element
-const fireBreath = await writer.create('ability', { name: 'Ember Breath' });
-await writer.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], remove: [] });
-
-// Walk every page of a type
-for await (const character of writer.listAll('character')) { /* ... */ }
-```
-
-## Bulk writes — always check `errors`
-
-`/bulk` **succeeds partially by default** (HTTP 200 with per-slot statuses). The one mistake to
-never make: treating a 200 as "everything landed."
-
-```typescript
-const res = await writer.bulk(
-  [
-    { type: 'character', element: { name: 'A' } },
-    { type: 'event', element: { name: 'B' } },
-  ],
-  { idempotencyKey: crypto.randomUUID() }, // mint FRESH per attempt — a failed batch is
-);                                          // cached under its key; never reuse across retries
-if (res.errors) {
-  for (const slot of res.items.filter((s) => s.status >= 400)) {
-    console.warn(slot.error?.code, slot.error?.message, slot.error?.doc_url);
-  }
-}
-// Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
-```
-
-## Sync
-
-```typescript
-let cursor; // opaque, never expires; persist it
-for await (const change of client.changesAll(cursor)) {
-  // ops arrive in (change_seq, id) order — apply in order → convergence
-}
-// GOTCHA: world-meta edits (name, calendar, public_read) do NOT enter /changes.
-// Poll client.getWorld() and compare updated_at separately.
-```
-
-## Errors
-
-Every non-2xx throws `OwApiError` carrying the platform envelope: `.status`, `.type`, `.code`,
-`.param` (the exact field that failed), and `.docUrl` — surface `docUrl` in your UX. Transport
-failures throw `OwNetworkError`. `err.isValidationError` is the common branch.
-
-## Canonical constants (all generated or test-gated from schema)
-
-```typescript
-import {
-  ELEMENT_TYPES,        // the 22 slugs (and the ElementType union)
-  ELEMENT_ICONS,        // Material Symbols icon per type
-  ELEMENT_LABELS,       // plural display labels
-  ELEMENT_SECTIONS,     // canonical field grouping + display order
-  FIELD_SCHEMA,         // per-field type/target metadata
-  elementColor,         // canonical colour: family carries COLOUR, icon carries TYPE
-} from '@onlyworlds/sdk';
-
-elementColor('character', 'dark'); // '#3987e5' — four CVD-validated families
-// Always pair colour with icon + label; colour alone is not accessible.
-```
-
-The full schema with per-field meaning lives in [SCHEMA.md](SCHEMA.md) (generated, ships in this
-package). AI agents: read [AGENTS.md](AGENTS.md) first.
-
-## Token rating system
-
-```typescript
-import { TokenResource } from '@onlyworlds/sdk';
-const tokens = new TokenResource(writer); // OwV2Client.request() satisfies TokenTransport
-const status = await tokens.getStatus();
-```
-
-## AI access — when to use which
-
-For **known, deterministic operations** (CRUD, sync, bulk) use this SDK — typed calls, no
-tool-schema overhead. For **live exploration of a user's world from a chat/agent context**, use
-the MCP server at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools;
-unaffected by SDK versioning).
-
-## License
-
-MIT
-
-## Links
-
-- [OnlyWorlds](https://www.onlyworlds.com) · [Docs](https://onlyworlds.github.io) · [API reference](https://www.onlyworlds.com/api/docs)
-- [Issues](https://github.com/OnlyWorlds/sdk/issues) · [CHANGELOG](CHANGELOG.md) · [Migration 3→4](docs/migrating-3-to-4.md)
+# OnlyWorlds TypeScript SDK
+
+[![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The canonical typed client for the [OnlyWorlds](https://onlyworlds.github.io) v2 API, plus the
+canonical constants (element types, icons, colour families, field schema) — generated from the
+same schema source the server runs on.
+
+**4.x is v2-native and ESM-only (Node 18+).** If you need the legacy v1 API dialect
+(`OnlyWorldsClient`) or CommonJS `require()`, stay on 3.x — it remains published and the v1 API
+remains served. See [docs/migrating-3-to-4.md](docs/migrating-3-to-4.md).
+
+## Installation
+
+```bash
+npm install @onlyworlds/sdk
+```
+
+## Quick Start
+
+```typescript
+import { OwV2Client } from '@onlyworlds/sdk';
+
+const client = new OwV2Client({ apiKey: 'ow_r_your_key' }); // read-only key: that's all you need
+const page = await client.list('character');                 // { data, has_more, next_cursor }
+```
+
+Key kinds: `ow_w_` write / `ow_r_` read-only (no PIN — the "give this to your players" key) /
+`ow_a_` account Bearer / 10-digit legacy. Writes on a PIN-protected world also pass `apiPin`.
+Demo keys `0000000000`–`0000000009` read real sample worlds.
+
+## The full round-trip
+
+```typescript
+const writer = new OwV2Client({ apiKey: 'ow_w_your_key', apiPin: '1234' });
+
+// v2 dialect rules, worth internalizing once:
+// - link fields use ONE bare name both directions (no _ids suffix — that's v1)
+// - NEVER send a "world" field (identity comes from the key; the client strips it anyway)
+const location = await writer.create('location', {
+  name: 'Dragon Peak',
+  description: 'A treacherous mountain peak where dragons nest',
+}); // id minted client-side when omitted (retries stay idempotent)
+
+const dragon = await writer.create('creature', {
+  name: 'Vorrath the Ember-Scaled',
+  location: location.id,            // single link: UUID (or null)
+});
+
+const fetched = await writer.get('creature', dragon.id);
+// fetched.location === location.id — reads the way it writes
+
+// PATCH is destructive on sent fields; arrays replace wholesale
+await writer.patch('location', location.id, { supertype: 'Mountain' });
+
+// For relationships, use the atomic link merge — returns the full updated element
+const fireBreath = await writer.create('ability', { name: 'Ember Breath' });
+await writer.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], remove: [] });
+
+// Walk every page of a type
+for await (const character of writer.listAll('character')) { /* ... */ }
+```
+
+## Bulk writes — always check `errors`
+
+`/bulk` **succeeds partially by default** (HTTP 200 with per-slot statuses). The one mistake to
+never make: treating a 200 as "everything landed."
+
+```typescript
+const res = await writer.bulk(
+  [
+    { type: 'character', element: { name: 'A' } },
+    { type: 'event', element: { name: 'B' } },
+  ],
+  { idempotencyKey: crypto.randomUUID() }, // mint FRESH per attempt — a failed batch is
+);                                          // cached under its key; never reuse across retries
+if (res.errors) {
+  for (const slot of res.items.filter((s) => s.status >= 400)) {
+    console.warn(slot.error?.code, slot.error?.message, slot.error?.doc_url);
+  }
+}
+// Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
+```
+
+## Sync
+
+```typescript
+let cursor; // opaque, never expires; persist it
+for await (const change of client.changesAll(cursor)) {
+  // ops arrive in (change_seq, id) order — apply in order → convergence
+}
+// GOTCHA: world-meta edits (name, calendar, public_read) do NOT enter /changes.
+// Poll client.getWorld() and compare updated_at separately.
+```
+
+## Errors
+
+Every non-2xx throws `OwApiError` carrying the platform envelope: `.status`, `.type`, `.code`,
+`.param` (the exact field that failed), and `.docUrl` — surface `docUrl` in your UX. Transport
+failures throw `OwNetworkError`. `err.isValidationError` is the common branch.
+
+## Canonical constants (all generated or test-gated from schema)
+
+```typescript
+import {
+  ELEMENT_TYPES,        // the 22 slugs (and the ElementType union)
+  ELEMENT_ICONS,        // Material Symbols icon per type
+  ELEMENT_LABELS,       // plural display labels
+  ELEMENT_SECTIONS,     // canonical field grouping + display order
+  FIELD_SCHEMA,         // per-field type/target metadata
+  elementColor,         // canonical colour: family carries COLOUR, icon carries TYPE
+} from '@onlyworlds/sdk';
+
+elementColor('character', 'dark'); // '#3987e5' — four CVD-validated families
+// Always pair colour with icon + label; colour alone is not accessible.
+```
+
+The full schema with per-field meaning lives in [SCHEMA.md](SCHEMA.md) (generated, ships in this
+package). AI agents: read [AGENTS.md](AGENTS.md) first.
+
+## Token rating system
+
+```typescript
+import { TokenResource } from '@onlyworlds/sdk';
+const tokens = new TokenResource(writer); // OwV2Client.request() satisfies TokenTransport
+const status = await tokens.getStatus();
+```
+
+## AI access — when to use which
+
+For **known, deterministic operations** (CRUD, sync, bulk) use this SDK — typed calls, no
+tool-schema overhead. For **live exploration of a user's world from a chat/agent context**, use
+the MCP server at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools;
+unaffected by SDK versioning).
+
+## License
+
+MIT
+
+## Links
+
+- [OnlyWorlds](https://www.onlyworlds.com) · [Docs](https://onlyworlds.github.io) · [API reference](https://www.onlyworlds.com/api/docs)
+- [Issues](https://github.com/OnlyWorlds/sdk/issues) · [CHANGELOG](CHANGELOG.md) · [Migration 3→4](docs/migrating-3-to-4.md)

package/dist/index.d.ts

@@ -26,6 +26,8 @@ interface OwElementBase {
 }
 type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
 declare const ELEMENT_TYPES: ElementType[];
+/** Canonical OnlyWorlds schema version. Source: canonical VERSION file, carried into keel schema/ by the refresh script (keel 492168c). */
+declare const ONLYWORLDS_VERSION: "00.30.00";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: keel's PRESENTATION-WRAPPER schema key `family:`
@@ -218,7 +220,9 @@ declare class OwNetworkError extends Error {
     constructor(message: string, cause: unknown);
 }
 /** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
-declare function parseEnvelope(status: number, body: unknown): OwApiError;
+/** Parse the platform ERROR envelope into an OwApiError. (Renamed from parseEnvelope in 4.0 —
+ *  distinct from the world-export envelope, which is a different artifact entirely.) */
+declare function parseErrorEnvelope(status: number, body: unknown): OwApiError;
 /** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
 declare function errorFromResponse(res: Response): Promise<OwApiError>;
 
@@ -422,7 +426,6 @@ declare const FAMILY_ORDER: readonly ElementFamily[];
  * Current OnlyWorlds version
  * Synced with https://github.com/OnlyWorlds/OnlyWorlds/blob/main/VERSION
  */
-declare const ONLYWORLDS_VERSION: "00.30.00";
 /**
  * Field type definitions for OnlyWorlds elements
  */
@@ -2373,7 +2376,8 @@ interface TokenTransport {
  *
  * Example usage:
  * ```typescript
- * const client = new OnlyWorldsClient({ apiKey, apiPin });
+ * const client = new OwV2Client({ apiKey: "ow_w_...", apiPin: "1234" });
+ * const tokens = new TokenResource(client);
  *
  * // Check token status
  * const status = await client.tokens.getStatus();
@@ -2390,6 +2394,12 @@ interface TokenTransport {
 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.
+     */
+    private req;
     /**
      * Get current token status for authenticated user
      *
@@ -2508,4 +2518,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, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };
+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, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation };

package/dist/index.js

@@ -29,7 +29,7 @@ var OwNetworkError = class extends Error {
     this.cause2 = cause;
   }
 };
-function parseEnvelope(status, body) {
+function parseErrorEnvelope(status, body) {
   const env = body && typeof body === "object" ? body : {};
   const nested = typeof env.error === "object" && env.error !== null ? env.error : void 0;
   const code = env.code ?? nested?.code ?? (typeof env.error === "string" ? env.error : null) ?? null;
@@ -48,7 +48,7 @@ async function errorFromResponse(res) {
   } catch {
     body = text || null;
   }
-  return parseEnvelope(res.status, body);
+  return parseErrorEnvelope(res.status, body);
 }
 
 // src/v2/keys.ts
@@ -314,6 +314,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
+var ONLYWORLDS_VERSION = "00.30.00";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",
@@ -485,7 +486,6 @@ function elementColor(type, mode = "dark") {
 var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
 
 // src/v2/constants.ts
-var ONLYWORLDS_VERSION = "00.30.00";
 var ELEMENT_LABELS = {
   ability: "Abilities",
   character: "Characters",
@@ -1150,6 +1150,21 @@ var TokenResource = class {
   constructor(client) {
     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.
+   */
+  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]";
+      }
+      throw err;
+    }
+  }
   /**
    * Get current token status for authenticated user
    *
@@ -1166,7 +1181,7 @@ var TokenResource = class {
    * ```
    */
   async getStatus() {
-    return this.client.request("GET", "/tokens/status/");
+    return this.req("GET", "/tokens/status/");
   }
   /**
    * Consume tokens for service usage
@@ -1197,7 +1212,7 @@ var TokenResource = class {
    * ```
    */
   async consume(params) {
-    return this.client.request("POST", "/tokens/consume/", {
+    return this.req("POST", "/tokens/consume/", {
       body: {
         amount: params.amount,
         service: params.service || "sdk_client",
@@ -1233,7 +1248,7 @@ var TokenResource = class {
    * ```
    */
   async getAccessKey() {
-    return this.client.request("GET", "/tokens/access-key/");
+    return this.req("GET", "/tokens/access-key/");
   }
   /**
    * Revoke a specific token session
@@ -1249,7 +1264,7 @@ var TokenResource = class {
    * ```
    */
   async revokeSession(sessionId) {
-    return this.client.request(
+    return this.req(
       "POST",
       `/tokens/revoke-session/?session_id=${encodeURIComponent(sessionId)}`
     );
@@ -1268,7 +1283,7 @@ var TokenResource = class {
    * ```
    */
   async revokeAllSessions() {
-    return this.client.request("POST", "/tokens/revoke-all-sessions/");
+    return this.req("POST", "/tokens/revoke-all-sessions/");
   }
   /**
    * Get public encryption info (no auth required)
@@ -1286,7 +1301,7 @@ var TokenResource = class {
    * ```
    */
   async getEncryptionInfo() {
-    return this.client.request("GET", "/tokens/encryption-info/");
+    return this.req("GET", "/tokens/encryption-info/");
   }
 };
 
@@ -1324,6 +1339,6 @@ export {
   getElementLabel,
   isDemoKey,
   kindCanWrite,
-  parseEnvelope,
+  parseErrorEnvelope,
   pinExpectation
 };

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@onlyworlds/sdk",
-  "version": "4.0.0-alpha.0",
-  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "types": "dist/index.d.ts",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "AGENTS.md",
-    "CHANGELOG.md",
-    "SCHEMA.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "pretest": "npm run build",
-    "test": "node --test \"test/**/*.test.mjs\"",
-    "codegen": "python codegen/generate_types.py",
-    "codegen:check": "python codegen/generate_types.py --check",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "onlyworlds",
-    "worldbuilding",
-    "api",
-    "sdk",
-    "typescript",
-    "rpg",
-    "ttrpg",
-    "game-development"
-  ],
-  "author": "OnlyWorlds",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OnlyWorlds/sdk.git"
-  },
-  "homepage": "https://onlyworlds.github.io/",
-  "bugs": {
-    "url": "https://github.com/OnlyWorlds/sdk/issues"
-  },
-  "devDependencies": {
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.5.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@onlyworlds/sdk",
+  "version": "4.0.0-alpha.1",
+  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "SCHEMA.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "pretest": "npm run build",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "codegen": "python codegen/generate_types.py",
+    "codegen:check": "python codegen/generate_types.py --check",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "onlyworlds",
+    "worldbuilding",
+    "api",
+    "sdk",
+    "typescript",
+    "rpg",
+    "ttrpg",
+    "game-development"
+  ],
+  "author": "OnlyWorlds",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OnlyWorlds/sdk.git"
+  },
+  "homepage": "https://onlyworlds.github.io/",
+  "bugs": {
+    "url": "https://github.com/OnlyWorlds/sdk/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}