@onlyworlds/sdk 2.2.2 → 3.0.0

package/dist/index.mjs

@@ -529,12 +529,12 @@ var FIELD_SCHEMA = {
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
     // Details
-    map: { type: "single_link", target: "map" },
-    zone: { type: "single_link", target: "zone" },
-    x: { type: "number" },
-    y: { type: "number" },
+    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" }
+    order: { type: "number", required: true }
   },
   narrative: {
     // Base fields (shared by all elements)
@@ -627,13 +627,13 @@ var FIELD_SCHEMA = {
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
     // Details
-    map: { type: "single_link", target: "map" },
-    element_type: { type: "text" },
-    // ElementType enum value
-    element_id: { type: "single_link", target: "any" },
+    map: { type: "single_link", target: "map", required: true },
+    element_type: { type: "text", required: true },
+    // 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" },
-    y: { type: "number" },
+    x: { type: "number", required: true },
+    y: { type: "number", required: true },
     z: { type: "number" }
   },
   relation: {
@@ -1190,19 +1190,343 @@ function getElementIcon(type) {
   }
   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";
+  }
+}
+
+// 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 ----------------------------------------------
+  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;
+  }
+};
+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"];
 export {
   ELEMENT_ICONS,
   ELEMENT_LABELS,
   ELEMENT_SECTIONS,
+  ELEMENT_TYPES,
   ElementType,
   FIELD_SCHEMA,
   GameTier,
   ONLYWORLDS_VERSION,
   OnlyWorldsClient,
+  OwApiError,
+  OwNetworkError,
+  OwV2Client,
+  SPATIAL_TYPES,
   createAnyElementId,
   createElementId,
   createElementIds,
+  detectKeyKind,
+  errorFromResponse,
   getElementIcon,
   getElementLabel,
-  getElementSections
+  getElementSections,
+  isDemoKey,
+  kindCanWrite,
+  parseEnvelope,
+  pinExpectation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "2.2.2",
+  "version": "3.0.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,6 +12,8 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "pretest": "npm run build",
+    "test": "node --test \"test/**/*.test.mjs\"",
     "prepublishOnly": "npm run build"
   },
   "keywords": [