@onlyworlds/sdk 3.0.0 → 4.0.0-alpha.0

package/AGENTS.md

@@ -0,0 +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.

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+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`)
+
+**v2-native only.** See `docs/migrating-3-to-4.md`. 3.x stays published forever for
+pinned consumers.
+
+### Removed (BREAKING)
+- The v1 client (`OnlyWorldsClient`), the v1 `ElementType` enum, `icon-utils`.
+  `ElementType` at the root is now THE v2 slug union (was `V2ElementType` alias in 3.x).
+- CJS build — the package is ESM-only with a sealed `exports` map (`"type": "module"`,
+  `sideEffects: false`).
+
+### Changed
+- Metadata tables (`ELEMENT_ICONS`, `ELEMENT_LABELS`, `ELEMENT_SECTIONS`, `FIELD_SCHEMA`,
+  `getElementIcon`, `getElementLabel`) ported onto the v2 slug union — same export names,
+  same shapes, contents byte-identical EXCEPT: `FIELD_SCHEMA` `type: 'number'` →
+  `'integer'` (70 entries; 'number' dropped from `FieldType`). Migration: consumers
+  switching on `'number'` switch on `'integer'`.
+- `TokenResource` now takes a structural `TokenTransport` (`{ request<T>(method, path,
+  body?) }`) instead of the removed v1 client. Token surface retained pending the
+  wire-fate ruling (RFC-001 §5) — may be removed in a later 4.x.
+
+### Added (post-alpha.0, same night)
+- **`ELEMENT_ICONS` GENERATED** from keel's `icon:` wrapper key (keel `56c124a`).
+- **`ELEMENT_SECTIONS` DERIVED** from the canonical schema's own document structure
+  (Skeld's ruling: sections are the standard tier's property groups; document order is
+  display order). Divergence check vs the old hand table found and fixed three fossils:
+  creature "Behaviour"→"Behavior", pin's triple-listed generic link → `element`,
+  relation "Involves" listing a nonexistent `relations` field. Canonical is truth.
+- **`SCHEMA.md`** — full generated schema reference (every field with its canonical
+  description, link directions, families, icons, sections), ships in the tarball;
+  covered by the codegen drift guard. AGENTS.md points agents at it first.
+- **`OwV2Client.request()` is public** (typed escape hatch; does not sanitize) and
+  structurally satisfies `TokenTransport` — `new TokenResource(client)` just works.
+  Token ruling (Skeld): keel keeps `/tokens/*` long-term; ported, not deleted.
+- 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).
+
+## [3.1.0] — 2026-07-23
+
+### Added
+- **Canonical element colour palette** (`src/v2/palette.ts`, exported from root):
+  `ELEMENT_FAMILIES` (type → family), `FAMILY_COLORS` (family → `{light, dark}` hex),
+  `familyOf(type)`, `elementColor(type, mode)`, `FAMILY_ORDER`, type `ElementFamily`.
+  Four semantic families (agents / world / abstract / temporal) ruled 2026-07-22 after
+  CVD-validated measurement (Orrery `product/schema/element-palette-measurements.md`).
+  Colour carries the FAMILY; `ELEMENT_ICONS` carries the TYPE. Keyed on the v2 slug
+  union. First proven live in atlas and council, whose local copies become re-exports.
+  **`ELEMENT_FAMILIES` is GENERATED** from the `family:` key in keel's schema YAML
+  (keel `c69366b`, a keel presentation-wrapper key — not part of the council-governed
+  OnlyWorlds standard); hexes are hand-authored design constants beside it. Membership
+  and hex invariants test-gated (`test/palette.test.mjs`); light hexes render-proven on
+  the ruled OnlyWorlds light mode (ow-house-light) 2026-07-23.
+- **Codegen drift guard**: `python codegen/generate_types.py --check` fails if
+  `types.generated.ts` doesn't match the schema YAMLs (release gate; mirrors keel's
+  schema CI job). Codegen also hard-fails on missing/invalid `family:` keys — the
+  canary for a canonical-refresh that overwrote keel's wrapper layer.
+- **CI**: GitHub Action building + running the full suite against the compiled bundle.
+- **AGENTS.md** shipped in the tarball — usage guide for AI agents reading the package
+  locally, including the SDK-vs-MCP division of labor and the wire gotchas.
+- README: worked create→link→read-back round-trip, schema-verified field by field
+  (also fixes the old example patching `'character'` with a location's id); canonical
+  colour section; SDK-vs-MCP guidance.
+- This CHANGELOG.
+
+### Fixed
+- `FieldType` union now includes `'number'` — the legacy alias that 70 `FIELD_SCHEMA`
+  entries actually carry (consumers switch on it; data normalization deferred to 4.0).
+- `generate_types.py` exits with a clear message when the sibling keel checkout is
+  absent instead of a bare traceback.
+
+## [3.0.0] — 2026-07-18
+
+- v2-native client (`OwV2Client`) absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+  wire-corrected against live staging fixtures (S22). Generated element types from the
+  canonical keel schema YAML (`src/v2/types.generated.ts`), validated against all 1,086
+  live W11 elements. v1 surface unchanged and frozen.

package/README.md

@@ -3,12 +3,13 @@
 [![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)
 
-A type-safe TypeScript SDK for building world-building applications with the OnlyWorlds API.
+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.
 
-The SDK speaks two dialects of the same API:
-
-- **v2 (`OwV2Client`)** -- the current, recommended default. Local-first shape: one-shape read/write (no `_ids` suffix), an opaque `/changes` sync feed, atomic bulk writes, and client-side UUID minting for safe retries. Base URL `https://www.onlyworlds.com/api/v2`.
-- **v1 (`OnlyWorldsClient`)** -- the original resource-style client. Fully served forever; kept below as the legacy section. Existing 2.x code keeps working unchanged -- v2 is purely additive.
+**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
 
@@ -16,294 +17,128 @@ The SDK speaks two dialects of the same API:
 npm install @onlyworlds/sdk
 ```
 
-## Quick Start (v2 -- recommended)
+## Quick Start
 
 ```typescript
 import { OwV2Client } from '@onlyworlds/sdk';
 
-const client = new OwV2Client({
-  apiKey: 'ow_w_your_world_key', // ow_w_ write / ow_r_ read / ow_a_ account / 10-digit legacy
-  apiPin: '1234',                // needed for writes on a PIN-protected world
-});
-// baseUrl defaults to https://www.onlyworlds.com/api/v2
-
-// Read a page, or walk every page of a type
-const page = await client.list('character');           // { data, has_more, next_cursor }
-for await (const character of client.listAll('character')) {
-  // ...
-}
-
-// Create -- id is minted client-side when omitted (retries stay idempotent)
-const location = await client.create('location', {
-  name: 'Dragon Peak',
-  description: 'A treacherous mountain peak where dragons nest',
-});
-
-// Partial update (arrays replace wholesale -- for links prefer editLinks)
-await client.patch('character', location.id, { name: 'Updated Name' });
-
-// Atomic link merge -- returns the full updated element
-await client.editLinks('event', eventId, 'objects', { add: [swordId], remove: [] });
-
-// Bulk write (up to ~1000; partial success by default, atomic:true for all-or-nothing)
-const res = await client.bulk([
-  { type: 'character', element: { name: 'A' } },
-  { type: 'event', element: { name: 'B' } },
-]);
-// res.items[i].status is the per-slot HTTP status; res.errors flags any failure
-
-// Sync: walk the opaque change feed and persist the final cursor
-let cursor;
-for await (const change of client.changesAll(cursor)) {
-  // apply change in order
-}
+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 }
 ```
 
-### AI-assistant access (MCP)
-
-An MCP server exists at `https://www.onlyworlds.com/mcp` for AI assistants (Claude and other MCP clients) to read and write worlds directly -- no SDK code required. See the [docs](https://onlyworlds.github.io) for setup.
+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.
 
-## Legacy: v1 client (`OnlyWorldsClient`)
-
-The v1 resource-style client remains fully supported and served forever. Prefer `OwV2Client` for new code.
+## The full round-trip
 
 ```typescript
-import { OnlyWorldsClient } from '@onlyworlds/sdk';
-
-const client = new OnlyWorldsClient({
-  apiKey: 'your-api-key',
-  apiPin: '1234'
-});
-// baseUrl defaults to https://www.onlyworlds.com/api/worldapi — only override it
-// when pointing at a different host (it must include the full API path)
-
-// Get your world (API keys are world-scoped)
-const world = await client.worlds.get();
-
-// Fetch characters (paginated)
-const characters = await client.characters.list();
+const writer = new OwV2Client({ apiKey: 'ow_w_your_key', apiPin: '1234' });
 
-// Create a new location
-const location = await client.locations.create({
+// 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',
-  supertype: 'mountain'
-});
-
-// Get a specific element
-const character = await client.characters.get('element-id');
+}); // id minted client-side when omitted (retries stay idempotent)
 
-// Update an element
-await client.characters.update('element-id', {
-  name: 'Updated Name'
+const dragon = await writer.create('creature', {
+  name: 'Vorrath the Ember-Scaled',
+  location: location.id,            // single link: UUID (or null)
 });
 
-// Delete an element
-await client.characters.delete('element-id');
-```
-
-## Features
-
-- ✅ **Full Type Safety** - Complete TypeScript definitions for all 22 OnlyWorlds element types
-- ✅ **Schema-Aligned Types** - Type definitions track the OnlyWorlds schema
-- ✅ **CRUD Operations** - Create, read, update, and delete operations for all elements
-- ✅ **Token Management** - Built-in support for OnlyWorlds token rating system
-- ✅ **Branded Types** - Compile-time safety for element relationships
-- ✅ **Zero Runtime Overhead** - Type system has no runtime cost
-- ✅ **Modern ESM/CJS** - Supports both ES modules and CommonJS
-
-## API Reference
-
-### World Endpoint
-
-The `worlds` resource is special because API keys are world-scoped (one key = one world). The endpoint returns a single `World` object directly, not a paginated list.
-
-```typescript
-// Get your world
-const world = await client.worlds.get();
-
-// Update your world
-const updated = await client.worlds.update({
-  description: 'A dark fantasy realm'
-});
-```
-
-**Note**: The `worlds` resource only has `get()` and `update()` methods (no `list()`, `create()`, or `delete()`) because API keys are world-scoped.
+const fetched = await writer.get('creature', dragon.id);
+// fetched.location === location.id — reads the way it writes
 
-### Element Endpoints
+// PATCH is destructive on sent fields; arrays replace wholesale
+await writer.patch('location', location.id, { supertype: 'Mountain' });
 
-All other element types return paginated results:
+// 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: [] });
 
-```typescript
-// List with pagination
-const response = await client.characters.list({
-  limit: 10,
-  offset: 0,
-  ordering: '-created_at',
-  search: 'dragon'
-});
-
-console.log(response.count);      // Total count
-console.log(response.results);    // Array of Characters
-console.log(response.next);       // URL for next page
-console.log(response.previous);   // URL for previous page
+// Walk every page of a type
+for await (const character of writer.listAll('character')) { /* ... */ }
 ```
 
-## Type-Safe Relationships
-
-```typescript
-import { ElementId, Character, Location } from '@onlyworlds/sdk';
-
-// Branded types ensure you can't mix up element IDs
-const locationId: ElementId<'Location'> = 'some-location-id';
-const character: Character = {
-  name: 'Aragorn',
-  location: locationId  // Type-safe!
-};
-```
-
-## Token Management
-
-OnlyWorlds provides a token rating system for tracking API usage and enabling AI-powered features. Users get a daily token allowance (default: 10,000 tokens) that resets every day.
-
-### Working Reference Implementation
+## Bulk writes — always check `errors`
 
-See [base-tool/src/llm/token-service.ts](https://github.com/OnlyWorlds/base-tool) for the complete working implementation that this SDK enables.
-
-### Check Token Status
+`/bulk` **succeeds partially by default** (HTTP 200 with per-slot statuses). The one mistake to
+never make: treating a 200 as "everything landed."
 
 ```typescript
-// Get current token status
-const status = await client.tokens.getStatus();
-
-console.log(`Available: ${status.tokens_available_today}/${status.token_rating}`);
-console.log(`Used today: ${status.tokens_used_today}`);
-console.log(`Active sessions: ${status.sessions_active}`);
-console.log(`Last reset: ${status.last_reset}`);
+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.
 ```
 
-### Consume Tokens
-
-Report token consumption when your tool uses AI features or other token-tracked services:
+## Sync
 
 ```typescript
-// Report token usage
-const result = await client.tokens.consume({
-  amount: 500,
-  service: 'my_worldbuilding_tool',
-  metadata: {
-    feature: 'character_generation',
-    model: 'gpt-4',
-    prompt_tokens: 300,
-    completion_tokens: 200
-  }
-});
-
-// Check if consumption succeeded
-if (result.error) {
-  console.warn('Token warning:', result.error);
+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
 }
-
-console.log(`Consumed ${result.tokens_consumed} tokens`);
-console.log(`${result.tokens_remaining} tokens remaining`);
+// GOTCHA: world-meta edits (name, calendar, public_read) do NOT enter /changes.
+// Poll client.getWorld() and compare updated_at separately.
 ```
 
-**Important**: The API allows consumption even when exceeding available tokens (tracks as debt), but returns a warning in the `error` field.
+## Errors
 
-### Advanced: Encrypted API Key Access
+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.
 
-For tools that need direct OpenAI API access using OnlyWorlds tokens:
+## Canonical constants (all generated or test-gated from schema)
 
 ```typescript
-// Get encrypted OpenAI key (requires 100+ tokens)
-const access = await client.tokens.getAccessKey();
-
-console.log('Session ID:', access.session_id);
-console.log('Expires:', access.expires_at);
-console.log('Available tokens:', access.tokens_available);
-
-// Decrypt the key client-side (see base-tool for full implementation)
-// 1. Derive decryption key from world ID using SHA-256
-// 2. Use 'fernet' npm package to decrypt
-// 3. Use decrypted OpenAI key for direct API calls
-// 4. Report usage with session_id
-
-// See base-tool/src/llm/token-service.ts:99-235 for complete example
+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.
 ```
 
-**Full decryption implementation** (based on base-tool):
+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.
 
-```typescript
-import { fernet } from 'fernet';
-
-// Derive decryption key from world ID
-async function deriveKey(worldId: string): Promise<string> {
-  const salt = 'onlyworlds-token-api-2024-public-salt';
-  const keyMaterial = `${worldId}:${salt}`;
-  const encoder = new TextEncoder();
-  const data = encoder.encode(keyMaterial);
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  const base64 = btoa(String.fromCharCode(...hashArray));
-  return base64.replace(/\+/g, '-').replace(/\//g, '_');
-}
-
-// Decrypt the API key
-async function decryptApiKey(encryptedKey: string, worldId: string): Promise<string> {
-  const derivedKey = await deriveKey(worldId);
-  const secret = new fernet.Secret(derivedKey);
-  const token = new fernet.Token({
-    secret: secret,
-    token: encryptedKey,
-    ttl: 0  // Don't enforce TTL client-side
-  });
-  return token.decode();
-}
-
-// Usage
-const world = await client.worlds.get();
-const access = await client.tokens.getAccessKey();
-const apiKey = await decryptApiKey(access.encrypted_key, world.id);
-
-// Use apiKey for OpenAI API calls, then report usage:
-await client.tokens.consume({
-  amount: tokensUsed,
-  sessionId: access.session_id,
-  service: 'direct_openai',
-  metadata: { model: 'gpt-4', /* ... */ }
-});
-```
-
-### Session Management
+## Token rating system
 
 ```typescript
-// Revoke a specific session
-await client.tokens.revokeSession(sessionId);
-
-// Revoke all sessions (emergency cleanup)
-const result = await client.tokens.revokeAllSessions();
-console.log(`Revoked ${result.sessions_revoked} sessions`);
+import { TokenResource } from '@onlyworlds/sdk';
+const tokens = new TokenResource(writer); // OwV2Client.request() satisfies TokenTransport
+const status = await tokens.getStatus();
 ```
 
-### Encryption Info
-
-Get public encryption details (no auth required):
+## AI access — when to use which
 
-```typescript
-const info = await client.tokens.getEncryptionInfo();
-console.log('Algorithm:', info.algorithm);
-console.log('Key derivation:', info.key_derivation);
-console.log('Public salt:', info.salt);
-console.log(info.javascript_example);
-```
+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 License - see [LICENSE](LICENSE) file for details
+MIT
 
 ## Links
 
-- [OnlyWorlds Website](https://onlyworlds.com)
-- [Documentation](https://onlyworlds.github.io/)
-- [NPM Package](https://www.npmjs.com/package/@onlyworlds/sdk)
-- [Report Issues](https://github.com/OnlyWorlds/sdk/issues)
+- [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)