@onlyworlds/sdk 3.0.0 → 4.0.0-alpha.0

package/dist/index.js

@@ -1,112 +1,373 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
+// src/v2/errors.ts
+var OwApiError = class extends Error {
+  constructor(status, code, message, docUrl, detail, type = null, param = null) {
+    super(message);
+    this.name = "OwApiError";
+    this.status = status;
+    this.code = code;
+    this.type = type;
+    this.param = param;
+    this.docUrl = docUrl;
+    this.detail = detail;
+  }
+  get isAuthError() {
+    return this.code === "invalid_credentials" || this.code === "key_revoked" || this.code === "world_gone";
+  }
+  /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
+  get isValidationError() {
+    return this.status === 422 || this.status === 400;
+  }
+  /** Same Idempotency-Key replayed with a different payload. */
+  get isIdempotencyConflict() {
+    return this.status === 409;
+  }
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+var OwNetworkError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "OwNetworkError";
+    this.cause2 = cause;
   }
-  return to;
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+function parseEnvelope(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;
+  const type = env.type ?? nested?.type ?? null;
+  const param = env.param ?? nested?.param ?? null;
+  const docUrl = env.doc_url ?? nested?.doc_url ?? null;
+  const message = env.message ?? nested?.message ?? (typeof env.detail === "string" ? env.detail : void 0) ?? `OnlyWorlds API error ${status}${code ? ` (${code})` : ""}`;
+  return new OwApiError(status, code, message, docUrl, body, type, param);
+}
+async function errorFromResponse(res) {
+  let body = null;
+  let text = "";
+  try {
+    text = await res.text();
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = text || null;
+  }
+  return parseEnvelope(res.status, body);
+}
 
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  ELEMENT_ICONS: () => ELEMENT_ICONS,
-  ELEMENT_LABELS: () => ELEMENT_LABELS,
-  ELEMENT_SECTIONS: () => ELEMENT_SECTIONS,
-  ELEMENT_TYPES: () => ELEMENT_TYPES,
-  ElementType: () => ElementType,
-  FIELD_SCHEMA: () => FIELD_SCHEMA,
-  GameTier: () => GameTier,
-  ONLYWORLDS_VERSION: () => ONLYWORLDS_VERSION,
-  OnlyWorldsClient: () => OnlyWorldsClient,
-  OwApiError: () => OwApiError,
-  OwNetworkError: () => OwNetworkError,
-  OwV2Client: () => OwV2Client,
-  SPATIAL_TYPES: () => SPATIAL_TYPES,
-  createAnyElementId: () => createAnyElementId,
-  createElementId: () => createElementId,
-  createElementIds: () => createElementIds,
-  detectKeyKind: () => detectKeyKind,
-  errorFromResponse: () => errorFromResponse,
-  getElementIcon: () => getElementIcon,
-  getElementLabel: () => getElementLabel,
-  getElementSections: () => getElementSections,
-  isDemoKey: () => isDemoKey,
-  kindCanWrite: () => kindCanWrite,
-  parseEnvelope: () => parseEnvelope,
-  pinExpectation: () => pinExpectation
-});
-module.exports = __toCommonJS(index_exports);
+// src/v2/keys.ts
+var LEGACY_RE = /^[0-9]{10}$/;
+function isDemoKey(key) {
+  return LEGACY_RE.test(key) && key >= "0000000000" && key <= "0000000009";
+}
+function detectKeyKind(key) {
+  if (key.startsWith("ow_w_")) return "write";
+  if (key.startsWith("ow_r_")) return "read";
+  if (key.startsWith("ow_a_")) return "account";
+  if (LEGACY_RE.test(key)) return "legacy";
+  return "unknown";
+}
+function kindCanWrite(kind) {
+  return kind === "write" || kind === "legacy";
+}
+function pinExpectation(kind) {
+  switch (kind) {
+    case "read":
+      return "never";
+    case "account":
+      return "never";
+    case "write":
+      return "optional";
+    case "legacy":
+      return "required-for-private-reads";
+    default:
+      return "optional";
+  }
+}
 
-// src/types.ts
-var ElementType = /* @__PURE__ */ ((ElementType2) => {
-  ElementType2["Ability"] = "ability";
-  ElementType2["Character"] = "character";
-  ElementType2["Collective"] = "collective";
-  ElementType2["Construct"] = "construct";
-  ElementType2["Creature"] = "creature";
-  ElementType2["Event"] = "event";
-  ElementType2["Family"] = "family";
-  ElementType2["Institution"] = "institution";
-  ElementType2["Language"] = "language";
-  ElementType2["Law"] = "law";
-  ElementType2["Location"] = "location";
-  ElementType2["Map"] = "map";
-  ElementType2["Marker"] = "marker";
-  ElementType2["Narrative"] = "narrative";
-  ElementType2["Object"] = "object";
-  ElementType2["Phenomenon"] = "phenomenon";
-  ElementType2["Pin"] = "pin";
-  ElementType2["Relation"] = "relation";
-  ElementType2["Species"] = "species";
-  ElementType2["Title"] = "title";
-  ElementType2["Trait"] = "trait";
-  ElementType2["Zone"] = "zone";
-  return ElementType2;
-})(ElementType || {});
-var ELEMENT_LABELS = {
-  ["ability" /* Ability */]: "Abilities",
-  ["character" /* Character */]: "Characters",
-  ["collective" /* Collective */]: "Collectives",
-  ["construct" /* Construct */]: "Constructs",
-  ["creature" /* Creature */]: "Creatures",
-  ["event" /* Event */]: "Events",
-  ["family" /* Family */]: "Families",
-  ["institution" /* Institution */]: "Institutions",
-  ["language" /* Language */]: "Languages",
-  ["law" /* Law */]: "Laws",
-  ["location" /* Location */]: "Locations",
-  ["map" /* Map */]: "Maps",
-  ["marker" /* Marker */]: "Markers",
-  ["narrative" /* Narrative */]: "Narratives",
-  ["object" /* Object */]: "Objects",
-  ["phenomenon" /* Phenomenon */]: "Phenomena",
-  ["pin" /* Pin */]: "Pins",
-  ["relation" /* Relation */]: "Relations",
-  ["species" /* Species */]: "Species",
-  ["title" /* Title */]: "Titles",
-  ["trait" /* Trait */]: "Traits",
-  ["zone" /* Zone */]: "Zones"
+// src/v2/client.ts
+var DEFAULT_BASE_URL = "https://www.onlyworlds.com/api/v2";
+var DEFAULT_PAGE_SIZE = 100;
+var DEFAULT_CHANGES_PAGE_SIZE = 100;
+var OwV2Client = class {
+  constructor(config) {
+    if (!config.apiKey) throw new Error("OwV2Client: apiKey is required");
+    this.apiKey = config.apiKey;
+    this.apiPin = config.apiPin || void 0;
+    this.keyKind = detectKeyKind(config.apiKey);
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE;
+    this.changesPageSize = config.changesPageSize ?? DEFAULT_CHANGES_PAGE_SIZE;
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("OwV2Client: no fetch available -- supply config.fetch");
+    }
+  }
+  // -- Health & world meta -------------------------------------------------
+  /** GET /health -- unauthenticated liveness pulse. */
+  async health() {
+    return this.request("GET", "/health/", { auth: false });
+  }
+  /**
+   * GET /world -- world meta (name, calendar/time fields, public_read).
+   * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
+   * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
+   */
+  async getWorld() {
+    return this.request("GET", "/world/");
+  }
+  /** PATCH /world -- partial world-meta update. */
+  async patchWorld(partial) {
+    return this.request("PATCH", "/world/", { body: sanitizePayload(partial) });
+  }
+  // -- Element CRUD --------------------------------------------------------
+  /** GET /{type}/ -- one cursor page. */
+  async list(type, params = {}) {
+    const query = buildQuery({
+      limit: params.limit ?? this.pageSize,
+      cursor: params.cursor,
+      expand: params.expand?.join(","),
+      fields: params.fields?.join(","),
+      ...params.filter
+    });
+    return this.request("GET", `/${type}/`, { query });
+  }
+  /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
+  async *listAll(type, params = {}) {
+    let cursor;
+    do {
+      const page = await this.list(type, { ...params, cursor });
+      for (const el of page.data) yield el;
+      cursor = page.has_more && page.next_cursor ? page.next_cursor : void 0;
+    } while (cursor);
+  }
+  /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
+  async get(type, id, opts = {}) {
+    const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(",") });
+    return this.request("GET", `/${type}/${id}/`, { query });
+  }
+  /**
+   * POST /{type}/ -- create. Mints an RFC-4122 UUID for element.id when the
+   * caller omits one (design ruling D29d) so a retry carrying the same
+   * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+   */
+  async create(type, element, opts = {}) {
+    const body = sanitizePayload(element);
+    if (body.id === void 0 || body.id === null || body.id === "") {
+      body.id = mintUuid();
+    }
+    return this.request("POST", `/${type}/`, {
+      body,
+      idempotencyKey: opts.idempotencyKey
+    });
+  }
+  /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+  async upsert(type, id, element) {
+    return this.request("PUT", `/${type}/${id}/`, { body: sanitizePayload(element) });
+  }
+  /**
+   * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
+   * replace wholesale, omitted fields stay untouched. For link arrays prefer
+   * editLinks() -- atomic server-side merge, no read-before-write.
+   */
+  async patch(type, id, partial) {
+    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial) });
+  }
+  /**
+   * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
+   * tombstone AND scrubs the id from every other element's links in the same
+   * transaction -- no client-side unlink pass needed, ever.
+   */
+  async delete(type, id) {
+    await this.request("DELETE", `/${type}/${id}/`, { allowEmpty: true });
+  }
+  /**
+   * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
+   * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
+   * updated element (fixture P5). Use this for all relationship editing; it
+   * retires the read-merge-PATCH dance.
+   */
+  async editLinks(type, id, field, edit) {
+    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit });
+  }
+  // -- Bulk ----------------------------------------------------------------
+  /**
+   * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
+   * always; inspect per-slot numeric `status` + top-level `errors` flag);
+   * atomic:true for all-or-nothing. Link validation runs against batch U
+   * database -- send in any order, cycles included; no client topo-sort.
+   * Success slots echo server-authoritative timestamps: set your sync baseline
+   * from this response alone. When an idempotencyKey is replayed, the returned
+   * response carries wasReplay:true (read from the Idempotent-Replay header).
+   */
+  async bulk(items, opts = {}) {
+    const body = {
+      items: items.map((it) => ({ type: it.type, element: sanitizePayload(it.element) })),
+      atomic: opts.atomic ?? false
+    };
+    return this.request("POST", "/bulk/", {
+      body,
+      idempotencyKey: opts.idempotencyKey,
+      replayAware: true
+    });
+  }
+  // -- Changes feed --------------------------------------------------------
+  /**
+   * GET /changes -- one page of the world's ordered change feed.
+   * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+   * Zero/absent cursor = full export (byte-aligned with the Folder Format).
+   * Rewind rule: if your persisted position is ahead of page.head, the server
+   * was restored -- re-baseline from cursor zero; do not assume caught-up.
+   * Citizenship: heaviest route on the platform; default page size is polite.
+   */
+  async changes(opts = {}) {
+    const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
+    return this.request("GET", "/changes/", { query });
+  }
+  /**
+   * Walk the feed from `since` (or from zero = full export) to the current
+   * tail, yielding ops in order. Returns the final cursor via the generator's
+   * return value; persist it for the next incremental pull.
+   */
+  async *changesAll(since) {
+    let cursor = since;
+    let page;
+    do {
+      page = await this.changes({ since: cursor });
+      for (const op of page.changes) yield op;
+      cursor = page.cursor;
+    } while (page.has_more);
+    return { cursor: page.cursor, head: page.head };
+  }
+  // -- Core request machinery ----------------------------------------------
+  /**
+   * Raw authenticated request against this client's baseUrl. Public since 4.0
+   * so auxiliary resources can ride the same transport — it structurally
+   * satisfies `TokenTransport` (`new TokenResource(client)`). Prefer the typed
+   * methods for element CRUD; this is the escape hatch, and it does NOT apply
+   * sanitizePayload — callers own their body shape.
+   */
+  async request(method, path, opts = {}) {
+    const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
+    const headers = {};
+    if (opts.auth !== false) {
+      if (this.keyKind === "account") {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      } else {
+        headers["API-Key"] = this.apiKey;
+        if (this.apiPin) headers["API-Pin"] = this.apiPin;
+      }
+    }
+    if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+    if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+      });
+    } catch (cause) {
+      throw new OwNetworkError(`OnlyWorlds request failed: ${method} ${path}`, cause);
+    }
+    if (!res.ok) throw await errorFromResponse(res);
+    if (res.status === 204 || opts.allowEmpty) {
+      const text = await res.text();
+      return text ? JSON.parse(text) : null;
+    }
+    const parsed = await res.json();
+    if (opts.replayAware && parsed && typeof parsed === "object") {
+      parsed.wasReplay = readReplayHeader(res.headers);
+    }
+    return parsed;
+  }
 };
-function getElementLabel(elementType) {
-  return ELEMENT_LABELS[elementType];
+var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq"];
+function sanitizePayload(payload) {
+  if (!payload || typeof payload !== "object") return payload;
+  const rest = { ...payload };
+  for (const field of READ_ONLY_FIELDS) delete rest[field];
+  return rest;
 }
+function readReplayHeader(headers) {
+  const v = headers.get("Idempotent-Replay");
+  return v != null && v.toLowerCase() === "true";
+}
+function mintUuid() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === "function") {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (let i = 0; i < 256; i++) hex.push((i + 256).toString(16).slice(1));
+  return hex[bytes[0]] + hex[bytes[1]] + hex[bytes[2]] + hex[bytes[3]] + "-" + hex[bytes[4]] + hex[bytes[5]] + "-" + hex[bytes[6]] + hex[bytes[7]] + "-" + hex[bytes[8]] + hex[bytes[9]] + "-" + hex[bytes[10]] + hex[bytes[11]] + hex[bytes[12]] + hex[bytes[13]] + hex[bytes[14]] + hex[bytes[15]];
+}
+function buildQuery(params) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0 && v !== null && v !== "") q.set(k, String(v));
+  }
+  return q.toString();
+}
+
+// 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 ELEMENT_FAMILIES = {
+  ability: "abstract",
+  character: "agents",
+  collective: "agents",
+  construct: "world",
+  creature: "agents",
+  event: "temporal",
+  family: "agents",
+  institution: "agents",
+  language: "abstract",
+  law: "abstract",
+  location: "world",
+  map: "world",
+  marker: "world",
+  narrative: "temporal",
+  object: "world",
+  phenomenon: "temporal",
+  pin: "world",
+  relation: "temporal",
+  species: "agents",
+  title: "abstract",
+  trait: "abstract",
+  zone: "world"
+};
+var ELEMENT_ICONS = {
+  ability: "auto_fix_normal",
+  character: "person",
+  collective: "groups_3",
+  construct: "api",
+  creature: "bug_report",
+  event: "saved_search",
+  family: "supervisor_account",
+  institution: "business",
+  language: "edit_road",
+  law: "gpp_bad",
+  location: "castle",
+  map: "map",
+  marker: "place",
+  narrative: "menu_book",
+  object: "webhook",
+  phenomenon: "thunderstorm",
+  pin: "push_pin",
+  relation: "link",
+  species: "crib",
+  title: "military_tech",
+  trait: "flaky",
+  zone: "architecture"
+};
 var ELEMENT_SECTIONS = {
-  ["ability" /* Ability */]: [
+  ability: [
     { name: "Mechanics", order: 1, fields: ["activation", "duration", "potency", "range", "effects", "challenges", "talents", "requisites"] },
     { name: "World", order: 2, fields: ["prevalence", "tradition", "source", "locus", "instruments", "systems"] }
   ],
-  ["character" /* Character */]: [
+  character: [
     { name: "Constitution", order: 1, fields: ["physicality", "mentality", "height", "weight", "species", "traits", "abilities"] },
     { name: "Origins", order: 2, fields: ["background", "motivations", "birth_date", "birthplace", "languages"] },
     { name: "World", order: 3, fields: ["reputation", "location", "objects", "institutions"] },
@@ -114,43 +375,43 @@ var ELEMENT_SECTIONS = {
     { name: "Social", order: 5, fields: ["family", "friends", "rivals"] },
     { name: "TTRPG", order: 6, fields: ["level", "hit_points", "STR", "DEX", "CON", "INT", "WIS", "CHA"] }
   ],
-  ["collective" /* Collective */]: [
+  collective: [
     { name: "Formation", order: 1, fields: ["composition", "count", "formation_date", "operator", "equipment"] },
     { name: "Dynamics", order: 2, fields: ["activity", "disposition", "state", "abilities", "symbolism"] },
     { name: "World", order: 3, fields: ["species", "characters", "creatures", "phenomena"] }
   ],
-  ["construct" /* Construct */]: [
+  construct: [
     { name: "Nature", order: 1, fields: ["rationale", "history", "status", "reach", "start_date", "end_date", "founder", "custodian"] },
     { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "relations", "titles", "constructs", "events", "narratives"] }
   ],
-  ["creature" /* Creature */]: [
+  creature: [
     { name: "Biology", order: 1, fields: ["appearance", "weight", "height", "species"] },
-    { name: "Behaviour", order: 2, fields: ["habits", "demeanor", "traits", "abilities", "languages"] },
+    { name: "Behavior", order: 2, fields: ["habits", "demeanor", "traits", "abilities", "languages"] },
     { name: "World", order: 3, fields: ["status", "birth_date", "location", "zone"] },
     { name: "TTRPG", order: 4, fields: ["challenge_rating", "hit_points", "armor_class", "speed", "actions"] }
   ],
-  ["event" /* Event */]: [
+  event: [
     { name: "Nature", order: 1, fields: ["history", "challenges", "consequences", "start_date", "end_date", "triggers"] },
     { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "relations", "titles", "constructs"] }
   ],
-  ["family" /* Family */]: [
+  family: [
     { name: "Identity", order: 1, fields: ["spirit", "history", "traditions", "traits", "abilities", "languages", "ancestors"] },
     { name: "World", order: 2, fields: ["reputation", "estates", "governs", "heirlooms", "creatures"] }
   ],
-  ["institution" /* Institution */]: [
+  institution: [
     { name: "Foundation", order: 1, fields: ["doctrine", "founding_date", "parent_institution"] },
     { name: "Claims", order: 2, fields: ["zones", "objects", "creatures"] },
     { name: "World", order: 3, fields: ["status", "allies", "adversaries", "constructs"] }
   ],
-  ["language" /* Language */]: [
+  language: [
     { name: "Structure", order: 1, fields: ["phonology", "grammar", "lexicon", "writing", "classification"] },
     { name: "World", order: 2, fields: ["status", "spread", "dialects"] }
   ],
-  ["law" /* Law */]: [
+  law: [
     { name: "Code", order: 1, fields: ["declaration", "purpose", "date", "parent_law", "penalties"] },
     { name: "World", order: 2, fields: ["author", "locations", "zones", "prohibitions", "adjudicators", "enforcers"] }
   ],
-  ["location" /* Location */]: [
+  location: [
     { name: "Setting", order: 1, fields: ["form", "function", "founding_date", "parent_location", "populations"] },
     { name: "Politics", order: 2, fields: ["political_climate", "primary_power", "governing_title", "secondary_powers", "zone", "rival", "partner"] },
     { name: "World", order: 3, fields: ["customs", "founders", "cults", "delicacies"] },
@@ -159,78 +420,95 @@ var ELEMENT_SECTIONS = {
     { name: "Construction", order: 6, fields: ["architecture", "buildings", "building_methods"] },
     { name: "Defense", order: 7, fields: ["defensibility", "elevation", "fighters", "defensive_objects"] }
   ],
-  ["map" /* Map */]: [
+  map: [
     { name: "Details", order: 1, fields: ["background_color", "hierarchy", "width", "height", "depth", "parent_map", "location"] }
   ],
-  ["marker" /* Marker */]: [
+  marker: [
     { name: "Details", order: 1, fields: ["map", "zone", "x", "y", "z", "order"] }
   ],
-  ["narrative" /* Narrative */]: [
+  narrative: [
     { name: "Context", order: 1, fields: ["story", "consequences", "start_date", "end_date", "order", "parent_narrative", "protagonist", "antagonist", "narrator", "conservator"] },
     { name: "Involves", order: 2, fields: ["events", "characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "relations", "titles", "constructs", "laws"] }
   ],
-  ["object" /* Object */]: [
+  object: [
     { name: "Form", order: 1, fields: ["aesthetics", "weight", "amount", "parent_object", "materials", "technology"] },
     { name: "Function", order: 2, fields: ["utility", "effects", "abilities", "consumes"] },
     { name: "World", order: 3, fields: ["origins", "location", "language", "affinities"] }
   ],
-  ["phenomenon" /* Phenomenon */]: [
+  phenomenon: [
     { name: "Mechanics", order: 1, fields: ["expression", "effects", "duration", "catalysts", "empowerments"] },
     { name: "World", order: 2, fields: ["mythology", "system", "triggers", "wielders", "environments"] }
   ],
-  ["pin" /* Pin */]: [
-    { name: "Details", order: 1, fields: ["map", "element_type", "element_id", "element", "x", "y", "z"] }
+  pin: [
+    { name: "Details", order: 1, fields: ["map", "element", "x", "y", "z"] }
   ],
-  ["relation" /* Relation */]: [
+  relation: [
     { name: "Nature", order: 1, fields: ["background", "start_date", "end_date", "intensity", "actor", "events"] },
-    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "relations", "titles", "constructs", "events", "narratives"] }
+    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "titles", "constructs", "events", "narratives"] }
   ],
-  ["species" /* Species */]: [
+  species: [
     { name: "Biology", order: 1, fields: ["appearance", "life_span", "weight", "nourishment", "reproduction", "adaptations"] },
     { name: "Psychology", order: 2, fields: ["instincts", "sociality", "temperament", "communication", "aggression", "traits"] },
     { name: "World", order: 3, fields: ["role", "parent_species", "locations", "zones", "affinities"] }
   ],
-  ["title" /* Title */]: [
+  title: [
     { name: "Mandate", order: 1, fields: ["authority", "eligibility", "grant_date", "revoke_date", "issuer", "body", "superior_title", "holders", "symbols"] },
     { name: "World", order: 2, fields: ["status", "history", "characters", "institutions", "families", "zones", "locations", "objects", "constructs", "laws", "collectives", "creatures", "phenomena", "species", "languages"] }
   ],
-  ["trait" /* Trait */]: [
+  trait: [
     { name: "Qualitative", order: 1, fields: ["social_effects", "physical_effects", "functional_effects", "personality_effects", "behaviour_effects"] },
     { name: "Quantitative", order: 2, fields: ["charisma", "coercion", "competence", "compassion", "creativity", "courage"] },
     { name: "World", order: 3, fields: ["significance", "anti_trait", "empowered_abilities"] }
   ],
-  ["zone" /* Zone */]: [
+  zone: [
     { name: "Scope", order: 1, fields: ["role", "start_date", "end_date", "phenomena", "linked_zones"] },
     { name: "World", order: 2, fields: ["context", "populations", "titles", "principles"] }
   ]
 };
-function getElementSections(elementType) {
-  return ELEMENT_SECTIONS[elementType] || [];
+
+// src/v2/types.ts
+var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
+
+// src/v2/palette.ts
+var FAMILY_COLORS = {
+  agents: { light: "#2a78d6", dark: "#3987e5" },
+  world: { light: "#008300", dark: "#008300" },
+  abstract: { light: "#e87ba4", dark: "#d55181" },
+  temporal: { light: "#eda100", dark: "#c98500" }
+};
+function familyOf(type) {
+  return ELEMENT_FAMILIES[type];
 }
+function elementColor(type, mode = "dark") {
+  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
+}
+var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
+
+// src/v2/constants.ts
 var ONLYWORLDS_VERSION = "00.30.00";
-var ELEMENT_ICONS = {
-  ["ability" /* Ability */]: "auto_fix_normal",
-  ["character" /* Character */]: "person",
-  ["collective" /* Collective */]: "groups_3",
-  ["construct" /* Construct */]: "api",
-  ["creature" /* Creature */]: "bug_report",
-  ["event" /* Event */]: "saved_search",
-  ["family" /* Family */]: "supervisor_account",
-  ["institution" /* Institution */]: "business",
-  ["language" /* Language */]: "edit_road",
-  ["law" /* Law */]: "gpp_bad",
-  ["location" /* Location */]: "castle",
-  ["map" /* Map */]: "map",
-  ["marker" /* Marker */]: "place",
-  ["narrative" /* Narrative */]: "menu_book",
-  ["object" /* Object */]: "webhook",
-  ["phenomenon" /* Phenomenon */]: "thunderstorm",
-  ["pin" /* Pin */]: "push_pin",
-  ["relation" /* Relation */]: "link",
-  ["species" /* Species */]: "crib",
-  ["title" /* Title */]: "military_tech",
-  ["trait" /* Trait */]: "flaky",
-  ["zone" /* Zone */]: "architecture"
+var ELEMENT_LABELS = {
+  ability: "Abilities",
+  character: "Characters",
+  collective: "Collectives",
+  construct: "Constructs",
+  creature: "Creatures",
+  event: "Events",
+  family: "Families",
+  institution: "Institutions",
+  language: "Languages",
+  law: "Laws",
+  location: "Locations",
+  map: "Maps",
+  marker: "Markers",
+  narrative: "Narratives",
+  object: "Objects",
+  phenomenon: "Phenomena",
+  pin: "Pins",
+  relation: "Relations",
+  species: "Species",
+  title: "Titles",
+  trait: "Traits",
+  zone: "Zones"
 };
 var FIELD_SCHEMA = {
   ability: {
@@ -242,9 +520,9 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Mechanics
     activation: { type: "text" },
-    duration: { type: "number" },
-    potency: { type: "number" },
-    range: { type: "number" },
+    duration: { type: "integer" },
+    potency: { type: "integer" },
+    range: { type: "integer" },
     effects: { type: "multi_link", target: "phenomenon" },
     challenges: { type: "text" },
     talents: { type: "multi_link", target: "trait" },
@@ -267,15 +545,15 @@ var FIELD_SCHEMA = {
     // Constitution
     physicality: { type: "text" },
     mentality: { type: "text" },
-    height: { type: "number" },
-    weight: { type: "number" },
+    height: { type: "integer" },
+    weight: { type: "integer" },
     species: { type: "multi_link", target: "species" },
     traits: { type: "multi_link", target: "trait" },
     abilities: { type: "multi_link", target: "ability" },
     // Origins
     background: { type: "text" },
     motivations: { type: "text" },
-    birth_date: { type: "number" },
+    birth_date: { type: "integer" },
     birthplace: { type: "single_link", target: "location" },
     languages: { type: "multi_link", target: "language" },
     // World
@@ -284,25 +562,25 @@ var FIELD_SCHEMA = {
     objects: { type: "multi_link", target: "object" },
     institutions: { type: "multi_link", target: "institution" },
     // Personality
-    charisma: { type: "number" },
-    coercion: { type: "number" },
-    competence: { type: "number" },
-    compassion: { type: "number" },
-    creativity: { type: "number" },
-    courage: { type: "number" },
+    charisma: { type: "integer" },
+    coercion: { type: "integer" },
+    competence: { type: "integer" },
+    compassion: { type: "integer" },
+    creativity: { type: "integer" },
+    courage: { type: "integer" },
     // Social
     family: { type: "multi_link", target: "family" },
     friends: { type: "multi_link", target: "character" },
     rivals: { type: "multi_link", target: "character" },
     // TTRPG
-    level: { type: "number" },
-    hit_points: { type: "number" },
-    STR: { type: "number" },
-    DEX: { type: "number" },
-    CON: { type: "number" },
-    INT: { type: "number" },
-    WIS: { type: "number" },
-    CHA: { type: "number" }
+    level: { type: "integer" },
+    hit_points: { type: "integer" },
+    STR: { type: "integer" },
+    DEX: { type: "integer" },
+    CON: { type: "integer" },
+    INT: { type: "integer" },
+    WIS: { type: "integer" },
+    CHA: { type: "integer" }
   },
   collective: {
     // Base fields (shared by all elements)
@@ -313,8 +591,8 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Formation
     composition: { type: "text" },
-    count: { type: "number" },
-    formation_date: { type: "number" },
+    count: { type: "integer" },
+    formation_date: { type: "integer" },
     operator: { type: "single_link", target: "institution" },
     equipment: { type: "multi_link", target: "construct" },
     // Dynamics
@@ -341,8 +619,8 @@ var FIELD_SCHEMA = {
     history: { type: "text" },
     status: { type: "text" },
     reach: { type: "text" },
-    start_date: { type: "number" },
-    end_date: { type: "number" },
+    start_date: { type: "integer" },
+    end_date: { type: "integer" },
     founder: { type: "single_link", target: "character" },
     custodian: { type: "single_link", target: "institution" },
     // Involves
@@ -374,8 +652,8 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Biology
     appearance: { type: "text" },
-    weight: { type: "number" },
-    height: { type: "number" },
+    weight: { type: "integer" },
+    height: { type: "integer" },
     species: { type: "multi_link", target: "species" },
     // Behaviour
     habits: { type: "text" },
@@ -385,14 +663,14 @@ var FIELD_SCHEMA = {
     languages: { type: "multi_link", target: "language" },
     // World
     status: { type: "text" },
-    birth_date: { type: "number" },
+    birth_date: { type: "integer" },
     location: { type: "single_link", target: "location" },
     zone: { type: "single_link", target: "zone" },
     // TTRPG
-    challenge_rating: { type: "number" },
-    hit_points: { type: "number" },
-    armor_class: { type: "number" },
-    speed: { type: "number" },
+    challenge_rating: { type: "integer" },
+    hit_points: { type: "integer" },
+    armor_class: { type: "integer" },
+    speed: { type: "integer" },
     actions: { type: "multi_link", target: "ability" }
   },
   event: {
@@ -406,8 +684,8 @@ var FIELD_SCHEMA = {
     history: { type: "text" },
     challenges: { type: "text" },
     consequences: { type: "text" },
-    start_date: { type: "number" },
-    end_date: { type: "number" },
+    start_date: { type: "integer" },
+    end_date: { type: "integer" },
     triggers: { type: "multi_link", target: "event" },
     // Involves
     characters: { type: "multi_link", target: "character" },
@@ -458,7 +736,7 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Foundation
     doctrine: { type: "text" },
-    founding_date: { type: "number" },
+    founding_date: { type: "integer" },
     parent_institution: { type: "single_link", target: "institution" },
     // Claims
     zones: { type: "multi_link", target: "zone" },
@@ -498,7 +776,7 @@ var FIELD_SCHEMA = {
     // Code
     declaration: { type: "text" },
     purpose: { type: "text" },
-    date: { type: "number" },
+    date: { type: "integer" },
     parent_law: { type: "single_link", target: "law" },
     penalties: { type: "multi_link", target: "construct" },
     // World
@@ -519,7 +797,7 @@ var FIELD_SCHEMA = {
     // Setting
     form: { type: "text" },
     function: { type: "text" },
-    founding_date: { type: "number" },
+    founding_date: { type: "integer" },
     parent_location: { type: "single_link", target: "location" },
     populations: { type: "multi_link", target: "collective" },
     // Politics
@@ -551,7 +829,7 @@ var FIELD_SCHEMA = {
     building_methods: { type: "multi_link", target: "construct" },
     // Defense
     defensibility: { type: "text" },
-    elevation: { type: "number" },
+    elevation: { type: "integer" },
     fighters: { type: "multi_link", target: "construct" },
     defensive_objects: { type: "multi_link", target: "object" }
   },
@@ -564,10 +842,10 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Details
     background_color: { type: "text" },
-    hierarchy: { type: "number" },
-    width: { type: "number" },
-    height: { type: "number" },
-    depth: { type: "number" },
+    hierarchy: { type: "integer" },
+    width: { type: "integer" },
+    height: { type: "integer" },
+    depth: { type: "integer" },
     parent_map: { type: "single_link", target: "map" },
     location: { type: "single_link", target: "location" }
   },
@@ -581,10 +859,10 @@ var FIELD_SCHEMA = {
     // Details
     map: { type: "single_link", target: "map", required: true },
     zone: { type: "single_link", target: "zone", required: true },
-    x: { type: "number", required: true },
-    y: { type: "number", required: true },
-    z: { type: "number" },
-    order: { type: "number", required: true }
+    x: { type: "integer", required: true },
+    y: { type: "integer", required: true },
+    z: { type: "integer" },
+    order: { type: "integer", required: true }
   },
   narrative: {
     // Base fields (shared by all elements)
@@ -596,9 +874,9 @@ var FIELD_SCHEMA = {
     // Context
     story: { type: "text" },
     consequences: { type: "text" },
-    start_date: { type: "number" },
-    end_date: { type: "number" },
-    order: { type: "number" },
+    start_date: { type: "integer" },
+    end_date: { type: "integer" },
+    order: { type: "integer" },
     parent_narrative: { type: "single_link", target: "narrative" },
     protagonist: { type: "single_link", target: "character" },
     antagonist: { type: "single_link", target: "character" },
@@ -633,8 +911,8 @@ var FIELD_SCHEMA = {
     image_url: { type: "text", required: false },
     // Form
     aesthetics: { type: "text" },
-    weight: { type: "number" },
-    amount: { type: "number" },
+    weight: { type: "integer" },
+    amount: { type: "integer" },
     parent_object: { type: "single_link", target: "object" },
     materials: { type: "multi_link", target: "construct" },
     technology: { type: "multi_link", target: "construct" },
@@ -659,7 +937,7 @@ var FIELD_SCHEMA = {
     // Mechanics
     expression: { type: "text" },
     effects: { type: "text" },
-    duration: { type: "number" },
+    duration: { type: "integer" },
     catalysts: { type: "multi_link", target: "object" },
     empowerments: { type: "multi_link", target: "ability" },
     // World
@@ -682,9 +960,9 @@ var FIELD_SCHEMA = {
     // ElementType enum value; YAML 'element' generic-link is split into _type + _id
     element_id: { type: "single_link", target: "any", required: true },
     // Can reference any element
-    x: { type: "number", required: true },
-    y: { type: "number", required: true },
-    z: { type: "number" }
+    x: { type: "integer", required: true },
+    y: { type: "integer", required: true },
+    z: { type: "integer" }
   },
   relation: {
     // Base fields (shared by all elements)
@@ -693,891 +971,359 @@ var FIELD_SCHEMA = {
     supertype: { type: "text", required: false },
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
-    // Nature
-    background: { type: "text" },
-    start_date: { type: "number" },
-    end_date: { type: "number" },
-    intensity: { type: "number" },
-    actor: { type: "single_link", target: "character" },
-    events: { type: "multi_link", target: "event" },
-    // Involves
-    characters: { type: "multi_link", target: "character" },
-    objects: { type: "multi_link", target: "object" },
-    locations: { type: "multi_link", target: "location" },
-    species: { type: "multi_link", target: "species" },
-    creatures: { type: "multi_link", target: "creature" },
-    institutions: { type: "multi_link", target: "institution" },
-    traits: { type: "multi_link", target: "trait" },
-    collectives: { type: "multi_link", target: "collective" },
-    zones: { type: "multi_link", target: "zone" },
-    abilities: { type: "multi_link", target: "ability" },
-    phenomena: { type: "multi_link", target: "phenomenon" },
-    languages: { type: "multi_link", target: "language" },
-    families: { type: "multi_link", target: "family" },
-    relations: { type: "multi_link", target: "relation" },
-    titles: { type: "multi_link", target: "title" },
-    constructs: { type: "multi_link", target: "construct" },
-    narratives: { type: "multi_link", target: "narrative" }
-  },
-  species: {
-    // Base fields (shared by all elements)
-    name: { type: "text", required: true },
-    description: { type: "text", required: false },
-    supertype: { type: "text", required: false },
-    subtype: { type: "text", required: false },
-    image_url: { type: "text", required: false },
-    // Biology
-    appearance: { type: "text" },
-    life_span: { type: "number" },
-    weight: { type: "number" },
-    nourishment: { type: "multi_link", target: "species" },
-    reproduction: { type: "multi_link", target: "construct" },
-    adaptations: { type: "multi_link", target: "ability" },
-    // Psychology
-    instincts: { type: "text" },
-    sociality: { type: "text" },
-    temperament: { type: "text" },
-    communication: { type: "text" },
-    aggression: { type: "number" },
-    traits: { type: "multi_link", target: "trait" },
-    // World
-    role: { type: "text" },
-    parent_species: { type: "single_link", target: "species" },
-    locations: { type: "multi_link", target: "location" },
-    zones: { type: "multi_link", target: "zone" },
-    affinities: { type: "multi_link", target: "phenomenon" }
-  },
-  title: {
-    // Base fields (shared by all elements)
-    name: { type: "text", required: true },
-    description: { type: "text", required: false },
-    supertype: { type: "text", required: false },
-    subtype: { type: "text", required: false },
-    image_url: { type: "text", required: false },
-    // Mandate
-    authority: { type: "text" },
-    eligibility: { type: "text" },
-    grant_date: { type: "number" },
-    revoke_date: { type: "number" },
-    issuer: { type: "single_link", target: "institution" },
-    body: { type: "single_link", target: "institution" },
-    superior_title: { type: "single_link", target: "title" },
-    holders: { type: "multi_link", target: "character" },
-    symbols: { type: "multi_link", target: "object" },
-    // World
-    status: { type: "text" },
-    history: { type: "text" },
-    characters: { type: "multi_link", target: "character" },
-    institutions: { type: "multi_link", target: "institution" },
-    families: { type: "multi_link", target: "family" },
-    zones: { type: "multi_link", target: "zone" },
-    locations: { type: "multi_link", target: "location" },
-    objects: { type: "multi_link", target: "object" },
-    constructs: { type: "multi_link", target: "construct" },
-    laws: { type: "multi_link", target: "law" },
-    collectives: { type: "multi_link", target: "collective" },
-    creatures: { type: "multi_link", target: "creature" },
-    phenomena: { type: "multi_link", target: "phenomenon" },
-    species: { type: "multi_link", target: "species" },
-    languages: { type: "multi_link", target: "language" }
-  },
-  trait: {
-    // Base fields (shared by all elements)
-    name: { type: "text", required: true },
-    description: { type: "text", required: false },
-    supertype: { type: "text", required: false },
-    subtype: { type: "text", required: false },
-    image_url: { type: "text", required: false },
-    // Qualitative
-    social_effects: { type: "text" },
-    physical_effects: { type: "text" },
-    functional_effects: { type: "text" },
-    personality_effects: { type: "text" },
-    behaviour_effects: { type: "text" },
-    // Quantitative
-    charisma: { type: "number" },
-    coercion: { type: "number" },
-    competence: { type: "number" },
-    compassion: { type: "number" },
-    creativity: { type: "number" },
-    courage: { type: "number" },
-    // World
-    significance: { type: "text" },
-    anti_trait: { type: "single_link", target: "trait" },
-    empowered_abilities: { type: "multi_link", target: "ability" }
+    // Nature
+    background: { type: "text" },
+    start_date: { type: "integer" },
+    end_date: { type: "integer" },
+    intensity: { type: "integer" },
+    actor: { type: "single_link", target: "character" },
+    events: { type: "multi_link", target: "event" },
+    // Involves
+    characters: { type: "multi_link", target: "character" },
+    objects: { type: "multi_link", target: "object" },
+    locations: { type: "multi_link", target: "location" },
+    species: { type: "multi_link", target: "species" },
+    creatures: { type: "multi_link", target: "creature" },
+    institutions: { type: "multi_link", target: "institution" },
+    traits: { type: "multi_link", target: "trait" },
+    collectives: { type: "multi_link", target: "collective" },
+    zones: { type: "multi_link", target: "zone" },
+    abilities: { type: "multi_link", target: "ability" },
+    phenomena: { type: "multi_link", target: "phenomenon" },
+    languages: { type: "multi_link", target: "language" },
+    families: { type: "multi_link", target: "family" },
+    relations: { type: "multi_link", target: "relation" },
+    titles: { type: "multi_link", target: "title" },
+    constructs: { type: "multi_link", target: "construct" },
+    narratives: { type: "multi_link", target: "narrative" }
   },
-  zone: {
+  species: {
     // Base fields (shared by all elements)
     name: { type: "text", required: true },
     description: { type: "text", required: false },
     supertype: { type: "text", required: false },
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
-    // Scope
-    role: { type: "text" },
-    start_date: { type: "number" },
-    end_date: { type: "number" },
-    phenomena: { type: "multi_link", target: "phenomenon" },
-    linked_zones: { type: "multi_link", target: "zone" },
+    // Biology
+    appearance: { type: "text" },
+    life_span: { type: "integer" },
+    weight: { type: "integer" },
+    nourishment: { type: "multi_link", target: "species" },
+    reproduction: { type: "multi_link", target: "construct" },
+    adaptations: { type: "multi_link", target: "ability" },
+    // Psychology
+    instincts: { type: "text" },
+    sociality: { type: "text" },
+    temperament: { type: "text" },
+    communication: { type: "text" },
+    aggression: { type: "integer" },
+    traits: { type: "multi_link", target: "trait" },
     // World
-    context: { type: "text" },
-    populations: { type: "multi_link", target: "collective" },
-    titles: { type: "multi_link", target: "title" },
-    principles: { type: "multi_link", target: "construct" }
-  }
-};
-function createElementId(id) {
-  return id;
-}
-function createElementIds(ids) {
-  return ids;
-}
-function createAnyElementId(id) {
-  return id;
-}
-
-// src/token-resource.ts
-var TokenResource = class {
-  constructor(client) {
-    this.client = client;
-  }
-  /**
-   * Get current token status for authenticated user
-   *
-   * Returns daily token allowance, usage, and availability.
-   * Matches base-tool's checkStatus() pattern.
-   *
-   * @returns Current token status
-   * @example
-   * ```typescript
-   * 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}`);
-   * ```
-   */
-  async getStatus() {
-    return this.client.request("GET", "/tokens/status/");
-  }
-  /**
-   * Consume tokens for service usage
-   *
-   * 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.
-   *
-   * @param params - Token consumption parameters
-   * @returns Consumption result with updated balance
-   * @example
-   * ```typescript
-   * const result = await client.tokens.consume({
-   *   amount: 500,
-   *   service: 'worldbuilding_tool',
-   *   metadata: {
-   *     feature: 'character_generation',
-   *     model: 'gpt-4',
-   *     prompt_tokens: 300,
-   *     completion_tokens: 200
-   *   }
-   * });
-   *
-   * if (result.error) {
-   *   console.warn('Token warning:', result.error);
-   * }
-   * console.log(`${result.tokens_remaining} tokens remaining`);
-   * ```
-   */
-  async consume(params) {
-    return this.client.request("POST", "/tokens/consume/", {
-      body: {
-        amount: params.amount,
-        service: params.service || "sdk_client",
-        session_id: params.sessionId ?? null,
-        metadata: params.metadata ?? null
-      }
-    });
-  }
-  /**
-   * Get encrypted OpenAI API key (advanced use case)
-   *
-   * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
-   * Returns encrypted key that must be decrypted client-side using Fernet.
-   *
-   * See base-tool/src/llm/token-service.ts:99-155 for full implementation example
-   * including client-side decryption with the 'fernet' npm package.
-   *
-   * @returns Encrypted access key and session info
-   * @throws Error if insufficient tokens (< 100)
-   * @example
-   * ```typescript
-   * // Get encrypted key
-   * const access = await client.tokens.getAccessKey();
-   *
-   * // Decrypt using fernet library (see base-tool for full example)
-   * // 1. Derive 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 access.session_id
-   *
-   * console.log('Session:', access.session_id);
-   * console.log('Expires:', access.expires_at);
-   * ```
-   */
-  async getAccessKey() {
-    return this.client.request("GET", "/tokens/access-key/");
-  }
-  /**
-   * Revoke a specific token session
-   *
-   * Invalidates the session ID obtained from getAccessKey().
-   * Use when cleaning up or on logout.
-   *
-   * @param sessionId - Session ID to revoke
-   * @returns Revocation result
-   * @example
-   * ```typescript
-   * await client.tokens.revokeSession('session-id-here');
-   * ```
-   */
-  async revokeSession(sessionId) {
-    return this.client.request(
-      "POST",
-      `/tokens/revoke-session/?session_id=${encodeURIComponent(sessionId)}`
-    );
-  }
-  /**
-   * Revoke all active sessions (emergency use)
-   *
-   * Invalidates all token sessions for the authenticated user.
-   * Use for security cleanup or when sessions are stuck.
-   *
-   * @returns Revocation result with count of revoked sessions
-   * @example
-   * ```typescript
-   * const result = await client.tokens.revokeAllSessions();
-   * console.log(`Revoked ${result.sessions_revoked} sessions`);
-   * ```
-   */
-  async revokeAllSessions() {
-    return this.client.request("POST", "/tokens/revoke-all-sessions/");
-  }
-  /**
-   * Get public encryption info (no auth required)
-   *
-   * Returns algorithm details and example code for client-side decryption.
-   * Public endpoint - can be called without authentication.
-   *
-   * @returns Encryption algorithm and implementation details
-   * @example
-   * ```typescript
-   * const info = await client.tokens.getEncryptionInfo();
-   * console.log('Algorithm:', info.algorithm);
-   * console.log('Key derivation:', info.key_derivation);
-   * console.log(info.javascript_example);
-   * ```
-   */
-  async getEncryptionInfo() {
-    return this.client.request("GET", "/tokens/encryption-info/");
-  }
-};
-
-// src/client.ts
-var Resource = class {
-  constructor(client, elementType) {
-    this.client = client;
-    this.elementType = elementType;
-  }
-  async list(options) {
-    const response = await this.client.request("GET", `/${this.elementType}/`, { params: options });
-    if (Array.isArray(response)) {
-      return {
-        count: response.length,
-        next: null,
-        previous: null,
-        results: response
-      };
-    }
-    return response;
-  }
-  async get(id) {
-    return this.client.request("GET", `/${this.elementType}/${id}/`);
-  }
-  async create(data) {
-    let body = OnlyWorldsClient.prepareRelations(data, this.elementType);
-    if (this.elementType === "pin") body = this.roundPinCoordinates(body);
-    return this.client.request("POST", `/${this.elementType}/`, { body });
-  }
-  async update(id, data) {
-    let body = OnlyWorldsClient.prepareRelations(data, this.elementType);
-    if (this.elementType === "pin") body = this.roundPinCoordinates(body);
-    return this.client.request("PATCH", `/${this.elementType}/${id}/`, { body });
-  }
-  async delete(id) {
-    return this.client.request("DELETE", `/${this.elementType}/${id}/`);
-  }
-  /**
-   * Round Pin coordinates to integers (API requirement)
-   * @private
-   */
-  roundPinCoordinates(data) {
-    const rounded = { ...data };
-    if (typeof rounded.x === "number") rounded.x = Math.round(rounded.x);
-    if (typeof rounded.y === "number") rounded.y = Math.round(rounded.y);
-    if (typeof rounded.z === "number") rounded.z = Math.round(rounded.z);
-    return rounded;
-  }
-};
-var WorldResource = class {
-  constructor(client) {
-    this.client = client;
-  }
-  /**
-   * Get the world associated with the current API key
-   * Returns the world directly (not wrapped in pagination)
-   */
-  async get() {
-    return this.client.request("GET", "/world/");
-  }
-  /**
-   * Update the current world
-   */
-  async update(data) {
-    return this.client.request("PATCH", "/world/", { body: data });
-  }
-};
-var OnlyWorldsClient = class {
-  constructor(config) {
-    this.baseUrl = config.baseUrl || "https://www.onlyworlds.com/api/worldapi";
-    this.headers = {
-      "Content-Type": "application/json",
-      "API-Key": config.apiKey,
-      "API-Pin": config.apiPin
-    };
-    this.worlds = new WorldResource(this);
-    this.tokens = new TokenResource(this);
-    this.abilities = new Resource(this, "ability");
-    this.characters = new Resource(this, "character");
-    this.collectives = new Resource(this, "collective");
-    this.constructs = new Resource(this, "construct");
-    this.creatures = new Resource(this, "creature");
-    this.events = new Resource(this, "event");
-    this.families = new Resource(this, "family");
-    this.institutions = new Resource(this, "institution");
-    this.languages = new Resource(this, "language");
-    this.laws = new Resource(this, "law");
-    this.locations = new Resource(this, "location");
-    this.maps = new Resource(this, "map");
-    this.markers = new Resource(this, "marker");
-    this.narratives = new Resource(this, "narrative");
-    this.objects = new Resource(this, "object");
-    this.phenomena = new Resource(this, "phenomenon");
-    this.pins = new Resource(this, "pin");
-    this.relations = new Resource(this, "relation");
-    this.species = new Resource(this, "species");
-    this.titles = new Resource(this, "title");
-    this.traits = new Resource(this, "trait");
-    this.zones = new Resource(this, "zone");
-  }
-  /**
-   * Make a request to the OnlyWorlds API
-   */
-  async request(method, path, options) {
-    const url = new URL(`${this.baseUrl}${path}`);
-    if (options?.params) {
-      Object.entries(options.params).forEach(([key, value]) => {
-        if (value !== void 0 && value !== null) {
-          url.searchParams.append(key, String(value));
-        }
-      });
-    }
-    const fetchOptions = {
-      method,
-      headers: this.headers
-    };
-    if (options?.body && ["POST", "PATCH", "PUT"].includes(method)) {
-      fetchOptions.body = JSON.stringify(options.body);
-    }
-    const response = await fetch(url.toString(), fetchOptions);
-    if (!response.ok) {
-      let errorMessage = `API Error ${response.status}`;
-      try {
-        const errorText = await response.text();
-        if (errorText) {
-          try {
-            const errorJson = JSON.parse(errorText);
-            if (Array.isArray(errorJson.detail)) {
-              const validationErrors = errorJson.detail.map((err) => {
-                const location = err.loc ? err.loc.join(".") : "unknown";
-                return `${location}: ${err.msg}`;
-              }).join("; ");
-              errorMessage += `: ${validationErrors}`;
-            } else {
-              errorMessage += `: ${errorJson.detail || errorJson.error || errorText}`;
-            }
-          } catch {
-            errorMessage += `: ${errorText}`;
-          }
-        }
-      } catch {
-      }
-      throw new Error(errorMessage);
-    }
-    if (response.status === 204) {
-      return void 0;
-    }
-    return response.json();
-  }
-  /**
-   * Helper to convert nested objects to _id/_ids format (legacy method)
-   * @deprecated Use prepareRelations instead - it's called automatically in create/update
-   */
-  static prepareInput(data) {
-    const result = { ...data };
-    for (const [key, value] of Object.entries(result)) {
-      if (value && typeof value === "object" && !Array.isArray(value) && "id" in value) {
-        delete result[key];
-        result[`${key}_id`] = value.id;
-      } else if (Array.isArray(value) && value.length > 0 && typeof value[0] === "object" && "id" in value[0]) {
-        delete result[key];
-        result[`${key}_ids`] = value.map((item) => item.id);
-      }
-    }
-    return result;
-  }
-  /**
-   * Convert relation fields to API format (_id/_ids suffix)
-   *
-   * The OnlyWorlds API expects:
-   * - single_link fields: fieldname_id (e.g., birthplace_id)
-   * - multi_link fields: fieldname_ids (e.g., species_ids)
-   *
-   * This method auto-converts based on FIELD_SCHEMA:
-   * - { species: ["id1", "id2"] } → { species_ids: ["id1", "id2"] }
-   * - { birthplace: "location-id" } → { birthplace_id: "location-id" }
-   * - { species: [{id: "id1", name: "X"}] } → { species_ids: ["id1"] }
-   *
-   * Called automatically by create() and update() methods.
-   */
-  static prepareRelations(data, elementType) {
-    const schema = FIELD_SCHEMA[elementType];
-    if (!schema) return data;
-    const result = { ...data };
-    for (const [key, value] of Object.entries(result)) {
-      const fieldDef = schema[key];
-      if (!fieldDef) continue;
-      if (fieldDef.type === "single_link") {
-        delete result[key];
-        if (value && typeof value === "object" && "id" in value) {
-          result[`${key}_id`] = value.id;
-        } else if (typeof value === "string" || value === null) {
-          result[`${key}_id`] = value;
-        }
-      } else if (fieldDef.type === "multi_link") {
-        delete result[key];
-        if (Array.isArray(value)) {
-          if (value.length > 0 && typeof value[0] === "object" && "id" in value[0]) {
-            result[`${key}_ids`] = value.map((item) => item.id);
-          } else {
-            result[`${key}_ids`] = value;
-          }
-        } else {
-          result[`${key}_ids`] = [];
-        }
-      }
-    }
-    return result;
+    role: { type: "text" },
+    parent_species: { type: "single_link", target: "species" },
+    locations: { type: "multi_link", target: "location" },
+    zones: { type: "multi_link", target: "zone" },
+    affinities: { type: "multi_link", target: "phenomenon" }
+  },
+  title: {
+    // Base fields (shared by all elements)
+    name: { type: "text", required: true },
+    description: { type: "text", required: false },
+    supertype: { type: "text", required: false },
+    subtype: { type: "text", required: false },
+    image_url: { type: "text", required: false },
+    // Mandate
+    authority: { type: "text" },
+    eligibility: { type: "text" },
+    grant_date: { type: "integer" },
+    revoke_date: { type: "integer" },
+    issuer: { type: "single_link", target: "institution" },
+    body: { type: "single_link", target: "institution" },
+    superior_title: { type: "single_link", target: "title" },
+    holders: { type: "multi_link", target: "character" },
+    symbols: { type: "multi_link", target: "object" },
+    // World
+    status: { type: "text" },
+    history: { type: "text" },
+    characters: { type: "multi_link", target: "character" },
+    institutions: { type: "multi_link", target: "institution" },
+    families: { type: "multi_link", target: "family" },
+    zones: { type: "multi_link", target: "zone" },
+    locations: { type: "multi_link", target: "location" },
+    objects: { type: "multi_link", target: "object" },
+    constructs: { type: "multi_link", target: "construct" },
+    laws: { type: "multi_link", target: "law" },
+    collectives: { type: "multi_link", target: "collective" },
+    creatures: { type: "multi_link", target: "creature" },
+    phenomena: { type: "multi_link", target: "phenomenon" },
+    species: { type: "multi_link", target: "species" },
+    languages: { type: "multi_link", target: "language" }
+  },
+  trait: {
+    // Base fields (shared by all elements)
+    name: { type: "text", required: true },
+    description: { type: "text", required: false },
+    supertype: { type: "text", required: false },
+    subtype: { type: "text", required: false },
+    image_url: { type: "text", required: false },
+    // Qualitative
+    social_effects: { type: "text" },
+    physical_effects: { type: "text" },
+    functional_effects: { type: "text" },
+    personality_effects: { type: "text" },
+    behaviour_effects: { type: "text" },
+    // Quantitative
+    charisma: { type: "integer" },
+    coercion: { type: "integer" },
+    competence: { type: "integer" },
+    compassion: { type: "integer" },
+    creativity: { type: "integer" },
+    courage: { type: "integer" },
+    // World
+    significance: { type: "text" },
+    anti_trait: { type: "single_link", target: "trait" },
+    empowered_abilities: { type: "multi_link", target: "ability" }
+  },
+  zone: {
+    // Base fields (shared by all elements)
+    name: { type: "text", required: true },
+    description: { type: "text", required: false },
+    supertype: { type: "text", required: false },
+    subtype: { type: "text", required: false },
+    image_url: { type: "text", required: false },
+    // Scope
+    role: { type: "text" },
+    start_date: { type: "integer" },
+    end_date: { type: "integer" },
+    phenomena: { type: "multi_link", target: "phenomenon" },
+    linked_zones: { type: "multi_link", target: "zone" },
+    // World
+    context: { type: "text" },
+    populations: { type: "multi_link", target: "collective" },
+    titles: { type: "multi_link", target: "title" },
+    principles: { type: "multi_link", target: "construct" }
   }
 };
-
-// src/token-types.ts
-var GameTier = /* @__PURE__ */ ((GameTier2) => {
-  GameTier2["FREE"] = "free";
-  GameTier2["SILVER"] = "silver";
-  GameTier2["GOLD"] = "gold";
-  GameTier2["PLATINUM"] = "platinum";
-  GameTier2["DIAMOND"] = "diamond";
-  GameTier2["DELUXE"] = "deluxe";
-  return GameTier2;
-})(GameTier || {});
-
-// src/icon-utils.ts
 var PLURAL_TO_SINGULAR = {
-  abilities: "ability" /* Ability */,
-  characters: "character" /* Character */,
-  collectives: "collective" /* Collective */,
-  constructs: "construct" /* Construct */,
-  creatures: "creature" /* Creature */,
-  events: "event" /* Event */,
-  families: "family" /* Family */,
-  institutions: "institution" /* Institution */,
-  languages: "language" /* Language */,
-  laws: "law" /* Law */,
-  locations: "location" /* Location */,
-  maps: "map" /* Map */,
-  markers: "marker" /* Marker */,
-  narratives: "narrative" /* Narrative */,
-  objects: "object" /* Object */,
-  phenomena: "phenomenon" /* Phenomenon */,
+  abilities: "ability",
+  characters: "character",
+  collectives: "collective",
+  constructs: "construct",
+  creatures: "creature",
+  events: "event",
+  families: "family",
+  institutions: "institution",
+  languages: "language",
+  laws: "law",
+  locations: "location",
+  maps: "map",
+  markers: "marker",
+  narratives: "narrative",
+  objects: "object",
+  phenomena: "phenomenon",
   // irregular plural
-  pins: "pin" /* Pin */,
-  relations: "relation" /* Relation */,
-  species: "species" /* Species */,
+  pins: "pin",
+  relations: "relation",
+  species: "species",
   // same singular/plural
-  titles: "title" /* Title */,
-  traits: "trait" /* Trait */,
-  zones: "zone" /* Zone */
+  titles: "title",
+  traits: "trait",
+  zones: "zone"
 };
 function getElementIcon(type) {
   const lower = type.toLowerCase();
   if (lower in PLURAL_TO_SINGULAR) {
     return ELEMENT_ICONS[PLURAL_TO_SINGULAR[lower]];
   }
-  const singular = Object.values(ElementType).find(
-    (et) => et.toLowerCase() === lower
-  );
+  const singular = ELEMENT_TYPES.find((et) => et.toLowerCase() === lower);
   if (singular) {
     return ELEMENT_ICONS[singular];
   }
   return "help_outline";
 }
-
-// src/v2/errors.ts
-var OwApiError = class extends Error {
-  constructor(status, code, message, docUrl, detail, type = null, param = null) {
-    super(message);
-    this.name = "OwApiError";
-    this.status = status;
-    this.code = code;
-    this.type = type;
-    this.param = param;
-    this.docUrl = docUrl;
-    this.detail = detail;
-  }
-  get isAuthError() {
-    return this.code === "invalid_credentials" || this.code === "key_revoked" || this.code === "world_gone";
-  }
-  /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
-  get isValidationError() {
-    return this.status === 422 || this.status === 400;
-  }
-  /** Same Idempotency-Key replayed with a different payload. */
-  get isIdempotencyConflict() {
-    return this.status === 409;
-  }
-};
-var OwNetworkError = class extends Error {
-  constructor(message, cause) {
-    super(message);
-    this.name = "OwNetworkError";
-    this.cause2 = cause;
-  }
-};
-function parseEnvelope(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;
-  const type = env.type ?? nested?.type ?? null;
-  const param = env.param ?? nested?.param ?? null;
-  const docUrl = env.doc_url ?? nested?.doc_url ?? null;
-  const message = env.message ?? nested?.message ?? (typeof env.detail === "string" ? env.detail : void 0) ?? `OnlyWorlds API error ${status}${code ? ` (${code})` : ""}`;
-  return new OwApiError(status, code, message, docUrl, body, type, param);
-}
-async function errorFromResponse(res) {
-  let body = null;
-  let text = "";
-  try {
-    text = await res.text();
-    body = text ? JSON.parse(text) : null;
-  } catch {
-    body = text || null;
-  }
-  return parseEnvelope(res.status, body);
-}
-
-// src/v2/keys.ts
-var LEGACY_RE = /^[0-9]{10}$/;
-function isDemoKey(key) {
-  return LEGACY_RE.test(key) && key >= "0000000000" && key <= "0000000009";
-}
-function detectKeyKind(key) {
-  if (key.startsWith("ow_w_")) return "write";
-  if (key.startsWith("ow_r_")) return "read";
-  if (key.startsWith("ow_a_")) return "account";
-  if (LEGACY_RE.test(key)) return "legacy";
-  return "unknown";
-}
-function kindCanWrite(kind) {
-  return kind === "write" || kind === "legacy";
-}
-function pinExpectation(kind) {
-  switch (kind) {
-    case "read":
-      return "never";
-    case "account":
-      return "never";
-    case "write":
-      return "optional";
-    case "legacy":
-      return "required-for-private-reads";
-    default:
-      return "optional";
-  }
+function getElementLabel(elementType) {
+  return ELEMENT_LABELS[elementType];
 }
 
-// src/v2/client.ts
-var DEFAULT_BASE_URL = "https://www.onlyworlds.com/api/v2";
-var DEFAULT_PAGE_SIZE = 100;
-var DEFAULT_CHANGES_PAGE_SIZE = 100;
-var OwV2Client = class {
-  constructor(config) {
-    if (!config.apiKey) throw new Error("OwV2Client: apiKey is required");
-    this.apiKey = config.apiKey;
-    this.apiPin = config.apiPin || void 0;
-    this.keyKind = detectKeyKind(config.apiKey);
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE;
-    this.changesPageSize = config.changesPageSize ?? DEFAULT_CHANGES_PAGE_SIZE;
-    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
-    if (typeof this.fetchImpl !== "function") {
-      throw new Error("OwV2Client: no fetch available -- supply config.fetch");
-    }
-  }
-  // -- Health & world meta -------------------------------------------------
-  /** GET /health -- unauthenticated liveness pulse. */
-  async health() {
-    return this.request("GET", "/health/", { auth: false });
-  }
-  /**
-   * GET /world -- world meta (name, calendar/time fields, public_read).
-   * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
-   * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
-   */
-  async getWorld() {
-    return this.request("GET", "/world/");
-  }
-  /** PATCH /world -- partial world-meta update. */
-  async patchWorld(partial) {
-    return this.request("PATCH", "/world/", { body: sanitizePayload(partial) });
-  }
-  // -- Element CRUD --------------------------------------------------------
-  /** GET /{type}/ -- one cursor page. */
-  async list(type, params = {}) {
-    const query = buildQuery({
-      limit: params.limit ?? this.pageSize,
-      cursor: params.cursor,
-      expand: params.expand?.join(","),
-      fields: params.fields?.join(","),
-      ...params.filter
-    });
-    return this.request("GET", `/${type}/`, { query });
-  }
-  /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
-  async *listAll(type, params = {}) {
-    let cursor;
-    do {
-      const page = await this.list(type, { ...params, cursor });
-      for (const el of page.data) yield el;
-      cursor = page.has_more && page.next_cursor ? page.next_cursor : void 0;
-    } while (cursor);
-  }
-  /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
-  async get(type, id, opts = {}) {
-    const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(",") });
-    return this.request("GET", `/${type}/${id}/`, { query });
-  }
-  /**
-   * POST /{type}/ -- create. Mints an RFC-4122 UUID for element.id when the
-   * caller omits one (design ruling D29d) so a retry carrying the same
-   * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
-   */
-  async create(type, element, opts = {}) {
-    const body = sanitizePayload(element);
-    if (body.id === void 0 || body.id === null || body.id === "") {
-      body.id = mintUuid();
-    }
-    return this.request("POST", `/${type}/`, {
-      body,
-      idempotencyKey: opts.idempotencyKey
-    });
-  }
-  /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
-  async upsert(type, id, element) {
-    return this.request("PUT", `/${type}/${id}/`, { body: sanitizePayload(element) });
-  }
-  /**
-   * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
-   * replace wholesale, omitted fields stay untouched. For link arrays prefer
-   * editLinks() -- atomic server-side merge, no read-before-write.
-   */
-  async patch(type, id, partial) {
-    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial) });
+// src/token-resource.ts
+var TokenResource = class {
+  constructor(client) {
+    this.client = client;
   }
   /**
-   * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
-   * tombstone AND scrubs the id from every other element's links in the same
-   * transaction -- no client-side unlink pass needed, ever.
+   * Get current token status for authenticated user
+   *
+   * Returns daily token allowance, usage, and availability.
+   * Matches base-tool's checkStatus() pattern.
+   *
+   * @returns Current token status
+   * @example
+   * ```typescript
+   * 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}`);
+   * ```
    */
-  async delete(type, id) {
-    await this.request("DELETE", `/${type}/${id}/`, { allowEmpty: true });
+  async getStatus() {
+    return this.client.request("GET", "/tokens/status/");
   }
   /**
-   * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
-   * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
-   * updated element (fixture P5). Use this for all relationship editing; it
-   * retires the read-merge-PATCH dance.
+   * Consume tokens for service usage
+   *
+   * 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.
+   *
+   * @param params - Token consumption parameters
+   * @returns Consumption result with updated balance
+   * @example
+   * ```typescript
+   * const result = await client.tokens.consume({
+   *   amount: 500,
+   *   service: 'worldbuilding_tool',
+   *   metadata: {
+   *     feature: 'character_generation',
+   *     model: 'gpt-4',
+   *     prompt_tokens: 300,
+   *     completion_tokens: 200
+   *   }
+   * });
+   *
+   * if (result.error) {
+   *   console.warn('Token warning:', result.error);
+   * }
+   * console.log(`${result.tokens_remaining} tokens remaining`);
+   * ```
    */
-  async editLinks(type, id, field, edit) {
-    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit });
+  async consume(params) {
+    return this.client.request("POST", "/tokens/consume/", {
+      body: {
+        amount: params.amount,
+        service: params.service || "sdk_client",
+        session_id: params.sessionId ?? null,
+        metadata: params.metadata ?? null
+      }
+    });
   }
-  // -- Bulk ----------------------------------------------------------------
   /**
-   * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
-   * always; inspect per-slot numeric `status` + top-level `errors` flag);
-   * atomic:true for all-or-nothing. Link validation runs against batch U
-   * database -- send in any order, cycles included; no client topo-sort.
-   * Success slots echo server-authoritative timestamps: set your sync baseline
-   * from this response alone. When an idempotencyKey is replayed, the returned
-   * response carries wasReplay:true (read from the Idempotent-Replay header).
+   * Get encrypted OpenAI API key (advanced use case)
+   *
+   * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
+   * Returns encrypted key that must be decrypted client-side using Fernet.
+   *
+   * See base-tool/src/llm/token-service.ts:99-155 for full implementation example
+   * including client-side decryption with the 'fernet' npm package.
+   *
+   * @returns Encrypted access key and session info
+   * @throws Error if insufficient tokens (< 100)
+   * @example
+   * ```typescript
+   * // Get encrypted key
+   * const access = await client.tokens.getAccessKey();
+   *
+   * // Decrypt using fernet library (see base-tool for full example)
+   * // 1. Derive 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 access.session_id
+   *
+   * console.log('Session:', access.session_id);
+   * console.log('Expires:', access.expires_at);
+   * ```
    */
-  async bulk(items, opts = {}) {
-    const body = {
-      items: items.map((it) => ({ type: it.type, element: sanitizePayload(it.element) })),
-      atomic: opts.atomic ?? false
-    };
-    return this.request("POST", "/bulk/", {
-      body,
-      idempotencyKey: opts.idempotencyKey,
-      replayAware: true
-    });
+  async getAccessKey() {
+    return this.client.request("GET", "/tokens/access-key/");
   }
-  // -- Changes feed --------------------------------------------------------
   /**
-   * GET /changes -- one page of the world's ordered change feed.
-   * Cursor is OPAQUE and never expires: persist verbatim, never parse.
-   * Zero/absent cursor = full export (byte-aligned with the Folder Format).
-   * Rewind rule: if your persisted position is ahead of page.head, the server
-   * was restored -- re-baseline from cursor zero; do not assume caught-up.
-   * Citizenship: heaviest route on the platform; default page size is polite.
+   * Revoke a specific token session
+   *
+   * Invalidates the session ID obtained from getAccessKey().
+   * Use when cleaning up or on logout.
+   *
+   * @param sessionId - Session ID to revoke
+   * @returns Revocation result
+   * @example
+   * ```typescript
+   * await client.tokens.revokeSession('session-id-here');
+   * ```
    */
-  async changes(opts = {}) {
-    const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
-    return this.request("GET", "/changes/", { query });
+  async revokeSession(sessionId) {
+    return this.client.request(
+      "POST",
+      `/tokens/revoke-session/?session_id=${encodeURIComponent(sessionId)}`
+    );
   }
   /**
-   * Walk the feed from `since` (or from zero = full export) to the current
-   * tail, yielding ops in order. Returns the final cursor via the generator's
-   * return value; persist it for the next incremental pull.
+   * Revoke all active sessions (emergency use)
+   *
+   * Invalidates all token sessions for the authenticated user.
+   * Use for security cleanup or when sessions are stuck.
+   *
+   * @returns Revocation result with count of revoked sessions
+   * @example
+   * ```typescript
+   * const result = await client.tokens.revokeAllSessions();
+   * console.log(`Revoked ${result.sessions_revoked} sessions`);
+   * ```
    */
-  async *changesAll(since) {
-    let cursor = since;
-    let page;
-    do {
-      page = await this.changes({ since: cursor });
-      for (const op of page.changes) yield op;
-      cursor = page.cursor;
-    } while (page.has_more);
-    return { cursor: page.cursor, head: page.head };
+  async revokeAllSessions() {
+    return this.client.request("POST", "/tokens/revoke-all-sessions/");
   }
-  // -- Core request machinery ----------------------------------------------
-  async request(method, path, opts = {}) {
-    const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
-    const headers = {};
-    if (opts.auth !== false) {
-      if (this.keyKind === "account") {
-        headers["Authorization"] = `Bearer ${this.apiKey}`;
-      } else {
-        headers["API-Key"] = this.apiKey;
-        if (this.apiPin) headers["API-Pin"] = this.apiPin;
-      }
-    }
-    if (opts.body !== void 0) headers["Content-Type"] = "application/json";
-    if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
-    let res;
-    try {
-      res = await this.fetchImpl(url, {
-        method,
-        headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
-      });
-    } catch (cause) {
-      throw new OwNetworkError(`OnlyWorlds request failed: ${method} ${path}`, cause);
-    }
-    if (!res.ok) throw await errorFromResponse(res);
-    if (res.status === 204 || opts.allowEmpty) {
-      const text = await res.text();
-      return text ? JSON.parse(text) : null;
-    }
-    const parsed = await res.json();
-    if (opts.replayAware && parsed && typeof parsed === "object") {
-      parsed.wasReplay = readReplayHeader(res.headers);
-    }
-    return parsed;
+  /**
+   * Get public encryption info (no auth required)
+   *
+   * Returns algorithm details and example code for client-side decryption.
+   * Public endpoint - can be called without authentication.
+   *
+   * @returns Encryption algorithm and implementation details
+   * @example
+   * ```typescript
+   * const info = await client.tokens.getEncryptionInfo();
+   * console.log('Algorithm:', info.algorithm);
+   * console.log('Key derivation:', info.key_derivation);
+   * console.log(info.javascript_example);
+   * ```
+   */
+  async getEncryptionInfo() {
+    return this.client.request("GET", "/tokens/encryption-info/");
   }
 };
-var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq"];
-function sanitizePayload(payload) {
-  if (!payload || typeof payload !== "object") return payload;
-  const rest = { ...payload };
-  for (const field of READ_ONLY_FIELDS) delete rest[field];
-  return rest;
-}
-function readReplayHeader(headers) {
-  const v = headers.get("Idempotent-Replay");
-  return v != null && v.toLowerCase() === "true";
-}
-function mintUuid() {
-  const c = globalThis.crypto;
-  if (c && typeof c.randomUUID === "function") return c.randomUUID();
-  const bytes = new Uint8Array(16);
-  if (c && typeof c.getRandomValues === "function") {
-    c.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
-  }
-  bytes[6] = bytes[6] & 15 | 64;
-  bytes[8] = bytes[8] & 63 | 128;
-  const hex = [];
-  for (let i = 0; i < 256; i++) hex.push((i + 256).toString(16).slice(1));
-  return hex[bytes[0]] + hex[bytes[1]] + hex[bytes[2]] + hex[bytes[3]] + "-" + hex[bytes[4]] + hex[bytes[5]] + "-" + hex[bytes[6]] + hex[bytes[7]] + "-" + hex[bytes[8]] + hex[bytes[9]] + "-" + hex[bytes[10]] + hex[bytes[11]] + hex[bytes[12]] + hex[bytes[13]] + hex[bytes[14]] + hex[bytes[15]];
-}
-function buildQuery(params) {
-  const q = new URLSearchParams();
-  for (const [k, v] of Object.entries(params)) {
-    if (v !== void 0 && v !== null && v !== "") q.set(k, String(v));
-  }
-  return q.toString();
-}
 
-// 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"];
-
-// src/v2/types.ts
-var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+// src/token-types.ts
+var GameTier = /* @__PURE__ */ ((GameTier2) => {
+  GameTier2["FREE"] = "free";
+  GameTier2["SILVER"] = "silver";
+  GameTier2["GOLD"] = "gold";
+  GameTier2["PLATINUM"] = "platinum";
+  GameTier2["DIAMOND"] = "diamond";
+  GameTier2["DELUXE"] = "deluxe";
+  return GameTier2;
+})(GameTier || {});
+export {
+  ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
   ELEMENT_SECTIONS,
   ELEMENT_TYPES,
-  ElementType,
+  FAMILY_COLORS,
+  FAMILY_ORDER,
   FIELD_SCHEMA,
   GameTier,
   ONLYWORLDS_VERSION,
-  OnlyWorldsClient,
   OwApiError,
   OwNetworkError,
   OwV2Client,
   SPATIAL_TYPES,
-  createAnyElementId,
-  createElementId,
-  createElementIds,
+  TokenResource,
   detectKeyKind,
+  elementColor,
   errorFromResponse,
+  familyOf,
   getElementIcon,
   getElementLabel,
-  getElementSections,
   isDemoKey,
   kindCanWrite,
   parseEnvelope,
   pinExpectation
-});
+};