@onlyworlds/sdk 2.2.3 → 3.1.0

package/AGENTS.md

@@ -0,0 +1,30 @@
+# For AI agents using @onlyworlds/sdk
+
+**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,44 @@
+# Changelog
+
+All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
+earlier history lives in git log only.
+
+## [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

@@ -5,22 +5,100 @@
 
 A type-safe TypeScript SDK for building world-building applications with the OnlyWorlds API.
 
+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.
+
 ## Installation
 
 ```bash
 npm install @onlyworlds/sdk
 ```
 
-## Quick Start
+## Quick Start (v2 -- recommended)
+
+```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')) {
+  // ...
+}
+
+// A worked round-trip: two elements, linked, read back. Byte-true v2 dialect:
+// link fields use ONE bare name both directions (no _ids suffix — that's v1),
+// and you NEVER send a "world" field (identity comes from the key; sending it 422s).
+const location = await client.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 client.create('creature', {
+  name: 'Vorrath the Ember-Scaled',
+  location: location.id,            // single link: UUID (or null)
+});
+
+const fetched = await client.get('creature', dragon.id);
+// fetched.location === location.id — reads the way it writes
+
+// Partial update (PATCH is destructive on sent fields; arrays replace wholesale)
+await client.patch('location', location.id, { supertype: 'Mountain' });
+
+// For relationships, prefer the atomic link merge -- returns the full updated element
+const fireBreath = await client.create('ability', { name: 'Ember Breath' });
+await client.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], 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
+}
+```
+
+### Canonical element colours
+
+```typescript
+import { elementColor, ELEMENT_FAMILIES, FAMILY_COLORS } from '@onlyworlds/sdk';
+
+elementColor('character', 'dark');  // '#3987e5' — colour carries the FAMILY
+// (agents / world / abstract / temporal); ELEMENT_ICONS carries the TYPE.
+// CVD-validated: always pair colour with icon + label, never colour alone.
+```
+
+### AI-assistant access (MCP) — and when to use which
+
+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.
+
+Division of labor: 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. Agents: see `AGENTS.md` in this package.
+
+## Legacy: v1 client (`OnlyWorldsClient`)
+
+The v1 resource-style client remains fully supported and served forever. Prefer `OwV2Client` for new code.
 
 ```typescript
 import { OnlyWorldsClient } from '@onlyworlds/sdk';
 
 const client = new OnlyWorldsClient({
   apiKey: 'your-api-key',
-  apiPin: '1234',
-  baseUrl: 'https://onlyworlds.com'
+  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();