@onlyworlds/sdk 4.8.1 → 4.10.0

package/AGENTS.md

@@ -27,6 +27,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
 - v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
 - PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- Offline or stale edits: pass `{ ifMatch: el.change_seq }` to `patch`/`editLinks` (since 4.9.0).
+  If the element moved, nothing is written and `OwPreconditionFailedError` (412) carries
+  `current`; the server never merges, the client decides.
 - World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
 - Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
   unknown unprefixed fields 422. Extensions are capped at **64 KB per element** (422,
@@ -37,6 +40,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Images: `uploadImage(bytes)` returns `{ url, ... }`; set `url` as `image_url`. The bytes go
   to the edge with a single-use ticket from keel, never with the API key. `removeImage(urlOrKey)`
   takes one back (its uploader or the world's owner); it leaves `image_url` on elements as is.
+- World files (no account needed; since 4.10.0): `readWorldFile(bytes)` opens a `.zip` holding one
+  world folder and returns `{ worldId, name, world, files: [{ path, data }] }`;
+  `writeWorldFile(files, topDir)` makes one. Refusals throw `OwWorldFileError` with a `reason`.
+  `world.json`'s `api` block (link and key) is removed both ways.
 - Ids: the client mints **UUIDv7** on an id-less `create` (since 4.2.0; keel mints v7 too).
   A v4 or v7 id you supply is accepted. **Never sort elements by id**: worlds mix v7, v4
   and legacy `06x…` ids (nibble 7 too, but seconds-first). For creation order use

package/CHANGELOG.md

@@ -5,6 +5,43 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.10.0] — 2026-10-11
+
+### Added
+- **World files.** `readWorldFile(bytes, { maxBytes, maxEntries, skip })` opens a `.zip` that
+  holds one world folder (Folder Format §4.1, a portable copy) and returns
+  `{ worldId, name, world, files }`; `writeWorldFile(files, topDir)` makes one. Bytes in,
+  bytes out: no DOM or file system, so it runs in the browser and in Node. Absorbed from
+  Atlas's reader (Temper's), so Atlas, Lantern and scripts open one file the same way.
+  The reader refuses before returning anything, with **`OwWorldFileError`** and a `reason`:
+  `unsafe_path` (climbs out, absolute, a drive, a backslash, an empty part, a path that is
+  both a file and a folder), `too_big` / `too_many` (1 GiB and 200,000 files uncompressed,
+  `WORLD_FILE_MAX_BYTES` / `WORLD_FILE_MAX_ENTRIES`; the inflated bytes are counted again,
+  since a declared size can lie), `not_a_world` (no `world.json`, unreadable, no string
+  `id`), `more_than_one` (two worlds, loose files beside the folder, a nested world.json),
+  `not_openable` (not a zip). Archive junk (`__MACOSX`, `.DS_Store`, `Thumbs.db`) is
+  dropped. `world.json`'s `api` (the link and its key) is removed on read and on write; a
+  `world.json` without one keeps its exact bytes. The writer refuses a `world.json` that will
+  not parse rather than zip it raw. Every world in a real Atlas folder (15, up to 3,832
+  files) round-trips byte for byte.
+- **First runtime dependency**: `fflate` (zip, no dependencies of its own, the one Atlas
+  uses). Tree-shaken away for code that never calls the world-file functions.
+
+## [4.9.0] — 2026-10-11
+
+### Added
+- **Only if unchanged (keel #210).** `patch(type, id, partial, { ifMatch })` and
+  `editLinks(type, id, field, edit, { ifMatch })` send `If-Match: "<change_seq>"`: the write
+  lands only if the element is still at that `change_seq`. When it has moved, nothing is
+  written and the call throws **`OwPreconditionFailedError`** (412 `precondition_failed`), an
+  `OwApiError` whose `current` is the element as it is now, so the client's re-read is free.
+  `OwApiError.isPreconditionFailed` names the case. The server never merges; the client
+  compares the copy it edited from with `current`. An `ifMatch` that is not a whole number
+  throws `TypeError` before anything is sent. Without `ifMatch`, nothing changes.
+  Checked live on keel-staging: a matching token lands, a stale one is refused with
+  `current` at the live `change_seq`, the refused write changes nothing, and the links
+  route behaves the same.
+
 ## [4.8.1] — 2026-10-11
 
 ### Changed

package/README.md

@@ -119,9 +119,41 @@ for await (const change of client.changesAll(cursor)) {
 
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 
+### Only if unchanged
+
+A client that edits offline, or from a copy it has held a while, can ask for an update to land only if nobody changed the element since it was read: pass the `change_seq` you read as `ifMatch`, on `patch` or `editLinks`.
+
+```typescript
+try {
+  await client.patch('character', el.id, { name: 'Mine' }, { ifMatch: el.change_seq });
+} catch (err) {
+  if (err instanceof OwPreconditionFailedError) {
+    // nothing was written; err.current is the element as it is now
+  }
+}
+```
+
+The check is per element and the server never merges. Compare the copy you edited from with `err.current`: when the fields you changed are not the ones that moved, send again with `ifMatch: err.current.change_seq`; when the same field moved on both sides, ask the user which to keep. Without `ifMatch` a write is unconditional, as before.
+
+## World files
+
+A world file is one `.zip` holding a whole world folder (`world.json` and `elements/<type>/*.json`, as Atlas keeps a world on disk), the way Atlas downloads and opens one. It needs no account and works in the browser and in Node.
+
+```typescript
+import { readWorldFile, writeWorldFile, OwWorldFileError } from '@onlyworlds/sdk';
+
+const world = readWorldFile(bytes);   // a Uint8Array
+world.worldId; world.name; world.world; // world.json, parsed
+world.files;                            // [{ path, data }], relative to the world's folder, sorted
+
+const zip = writeWorldFile(world.files, 'hollow-reach-0192a000'); // one top-level folder
+```
+
+The reader refuses a file before returning anything: a path that could land outside the folder, more than 1 GiB or 200,000 files uncompressed (`maxBytes`, `maxEntries` to change them), no `world.json` with an `id`, or more than one world. Check `err.reason` on the `OwWorldFileError` it throws. The world's OnlyWorlds link and key (`world.json`'s `api`) never travel: both functions remove them. A tool's own folder (`.atlas/` and the like) comes back like any other file; pass `skip: path => …` to leave files out.
+
 ## Errors
 
-Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case.
+Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case. A write sent with `ifMatch` that found the element moved throws `OwPreconditionFailedError` (412, `err.isPreconditionFailed`), an `OwApiError` that also carries `current`.
 
 ## Schema constants
 

package/dist/index.d.ts

@@ -2132,6 +2132,25 @@ declare class OwApiError extends Error {
      * key never sees it.
      */
     get isOwnerOnly(): boolean;
+    /**
+     * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
+     * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
+     * merged. The error is an OwPreconditionFailedError; its `current` is the element as it
+     * is now, so no second read is needed.
+     */
+    get isPreconditionFailed(): boolean;
+}
+/**
+ * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
+ * `ifMatch`. `current` is the element as it is now, as this key sees it (keel sends it beside
+ * the error envelope; null if a response ever lacks it). The check is per element and the
+ * server never merges: compare the copy you edited from with `current`; when the fields you
+ * changed are not the ones that moved, re-send with `ifMatch: current.change_seq`; when the
+ * same field moved on both sides, ask the user which to keep.
+ */
+declare class OwPreconditionFailedError extends OwApiError {
+    readonly current: Record<string, unknown> | null;
+    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null, retryAfter?: number | null);
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2227,8 +2246,15 @@ declare class OwV2Client {
      * 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.
+     *
+     * `ifMatch` (keel #210): the element's `change_seq` as you read it. The update lands
+     * only if nobody changed the element since; otherwise nothing is written and this throws
+     * an OwPreconditionFailedError (412) whose `current` is the element as it is now. Omit
+     * it for today's unconditional write.
      */
-    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
+    patch(type: ElementType | string, id: string, partial: Record<string, unknown>, opts?: {
+        ifMatch?: number;
+    }): Promise<OwElement>;
     /**
      * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
      * tombstone AND scrubs the id from every other element's links in the same
@@ -2239,9 +2265,12 @@ declare class OwV2Client {
      * 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.
+     * retires the read-merge-PATCH dance. `ifMatch` works as on patch(): a link write
+     * moves the element too.
      */
-    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
+    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit, opts?: {
+        ifMatch?: number;
+    }): Promise<OwElement>;
     /**
      * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
      * always; inspect per-slot numeric `status` + top-level `errors` flag);
@@ -2353,6 +2382,8 @@ declare class OwV2Client {
         auth?: boolean;
         allowEmpty?: boolean;
         replayAware?: boolean;
+        /** A `change_seq` to send as `If-Match` (keel #210); a whole number, else TypeError before sending. */
+        ifMatch?: number;
     }): Promise<T>;
 }
 
@@ -2428,6 +2459,73 @@ declare function getElementIcon(type: string): string;
 /** Plural display label for an element type (e.g. phenomenon → "Phenomena"). */
 declare function getElementLabel(elementType: ElementType): string;
 
+/**
+ * The world file: one `.zip` holding one whole world as a portable copy
+ * (Folder Format spec §4.1, "a portable copy"), and the reader that opens one
+ * back. Absorbed from Atlas's `src/store/world-file.ts` (Temper's, Atlas
+ * 1.17), so Atlas, Lantern and any script read one file the same way.
+ *
+ * THE FILE: one top-level folder holding every file of the world as it sits
+ * on disk, except the OnlyWorlds link and its key (`world.json` without `api`).
+ * JSON is deflated, everything else stored. A world.json at the root, with no
+ * folder, reads the same.
+ *
+ * THE READER takes bytes and returns bytes: no DOM, `File` or file system, so
+ * it runs in a browser and in Node alike. It refuses, before returning
+ * anything: a path that climbs out, is absolute, names a drive, holds a
+ * backslash or an empty part, or is both a file and a folder; a declared size
+ * or a file count past the budget (and the inflated bytes are counted again,
+ * since a declared size can lie); no world, more than one world, files
+ * outside the world's folder, a world.json nested inside the world; and a
+ * world.json that will not parse or has no string `id`. Archive junk
+ * (`__MACOSX`, `.DS_Store`, `Thumbs.db`) is dropped.
+ *
+ * A tool's own `.<tool>/` folder is the tool's (spec §4): this module knows
+ * none of them. A caller that leaves some of its files out passes `skip`.
+ */
+/** What one world file may hold, uncompressed: Atlas's budget, the writer's and the reader's alike. */
+declare const WORLD_FILE_MAX_BYTES: number;
+declare const WORLD_FILE_MAX_ENTRIES = 200000;
+type OwWorldFileReason = 'unsafe_path' | 'too_big' | 'too_many' | 'not_a_world' | 'more_than_one' | 'not_openable';
+/** A world file was refused; nothing was returned. `reason` says why, for a tool to word its own message. */
+declare class OwWorldFileError extends Error {
+    readonly reason: OwWorldFileReason;
+    constructor(reason: OwWorldFileReason, message?: string);
+}
+interface OwWorldFileEntry {
+    /** Relative to the world's folder, `/`-separated. */
+    path: string;
+    data: Uint8Array;
+}
+interface OwReadWorldFile {
+    worldId: string;
+    /** `world.json`'s `name` as the file has it; `''` when it has none. */
+    name: string;
+    /** `world.json`, parsed, without `api`. */
+    world: Record<string, unknown>;
+    /** The world's files, relative to its folder, `world.json` included (without `api`), sorted by path. */
+    files: OwWorldFileEntry[];
+}
+interface OwReadWorldFileOptions {
+    maxBytes?: number;
+    maxEntries?: number;
+    /** Leave a file out of `files` (a path relative to the world's folder). It still counts against the budget. */
+    skip?: (path: string) => boolean;
+}
+/**
+ * Read a world file. Throws `OwWorldFileError` saying why, having returned
+ * nothing; the caller writes only what this returns.
+ */
+declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions): OwReadWorldFile;
+/**
+ * Write a world file: every file under one top-level folder `topDir`, JSON
+ * deflated, everything else stored, `world.json` without `api`. Refuses
+ * (`OwWorldFileError`) an unsafe path or `topDir`, a duplicate path, and a
+ * world.json that is missing, will not parse (it may hold a key, so it is
+ * never zipped raw) or has no `id`.
+ */
+declare function writeWorldFile(files: OwWorldFileEntry[], topDir: string): Uint8Array;
+
 /**
  * OnlyWorlds Token Management API Types
  *
@@ -2712,4 +2810,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwMediaTicket, OwNetworkError, type OwPage, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation };
+export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwMediaTicket, OwNetworkError, type OwPage, OwPreconditionFailedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation, readWorldFile, writeWorldFile };

package/dist/index.js

@@ -66,6 +66,23 @@ var OwApiError = class extends Error {
   get isOwnerOnly() {
     return this.status === 403 && this.code === "owner_only";
   }
+  /**
+   * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
+   * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
+   * merged. The error is an OwPreconditionFailedError; its `current` is the element as it
+   * is now, so no second read is needed.
+   */
+  get isPreconditionFailed() {
+    return this.status === 412 && this.code === "precondition_failed";
+  }
+};
+var OwPreconditionFailedError = class extends OwApiError {
+  constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
+    super(status, code, message, docUrl, detail, type, param, retryAfter);
+    this.name = "OwPreconditionFailedError";
+    const cur = detail && typeof detail === "object" ? detail.current : void 0;
+    this.current = cur && typeof cur === "object" ? cur : null;
+  }
 };
 var OwNetworkError = class extends Error {
   constructor(message, cause) {
@@ -82,7 +99,8 @@ function parseErrorEnvelope(status, body, retryAfter = 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, retryAfter);
+  const Cls = status === 412 && code === "precondition_failed" ? OwPreconditionFailedError : OwApiError;
+  return new Cls(status, code, message, docUrl, body, type, param, retryAfter);
 }
 function parseRetryAfter(value, now = Date.now()) {
   if (value == null) return null;
@@ -221,9 +239,14 @@ var OwV2Client = class {
    * 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.
+   *
+   * `ifMatch` (keel #210): the element's `change_seq` as you read it. The update lands
+   * only if nobody changed the element since; otherwise nothing is written and this throws
+   * an OwPreconditionFailedError (412) whose `current` is the element as it is now. Omit
+   * it for today's unconditional write.
    */
-  async patch(type, id, partial) {
-    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial) });
+  async patch(type, id, partial, opts = {}) {
+    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
    * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
@@ -237,10 +260,11 @@ var OwV2Client = class {
    * 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.
+   * retires the read-merge-PATCH dance. `ifMatch` works as on patch(): a link write
+   * moves the element too.
    */
-  async editLinks(type, id, field, edit) {
-    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit });
+  async editLinks(type, id, field, edit, opts = {}) {
+    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit, ifMatch: opts.ifMatch });
   }
   // -- Bulk ----------------------------------------------------------------
   /**
@@ -395,6 +419,9 @@ var OwV2Client = class {
    * sanitizePayload — callers own their body shape.
    */
   async request(method, path, opts = {}) {
+    if (opts.ifMatch !== void 0 && !(Number.isInteger(opts.ifMatch) && opts.ifMatch >= 0)) {
+      throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
+    }
     const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
     const headers = {};
     if (opts.auth !== false) {
@@ -407,6 +434,7 @@ var OwV2Client = class {
     }
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";
     if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    if (opts.ifMatch !== void 0) headers["If-Match"] = `"${opts.ifMatch}"`;
     let res;
     try {
       res = await this.fetchImpl(url, {
@@ -1305,6 +1333,140 @@ function getElementLabel(elementType) {
   return ELEMENT_LABELS[elementType];
 }
 
+// src/world-file.ts
+import { unzipSync, zipSync } from "fflate";
+var WORLD_FILE = "world.json";
+var WORLD_FILE_MAX_BYTES = 1024 ** 3;
+var WORLD_FILE_MAX_ENTRIES = 2e5;
+var MESSAGES = {
+  unsafe_path: "The world file holds a path that cannot be written safely.",
+  too_big: "The world file is bigger than the budget allows.",
+  too_many: "The world file holds more files than the budget allows.",
+  not_a_world: "The file is not a world: it has no readable world.json with an id.",
+  more_than_one: "The file holds more than one world, or files outside the world's folder.",
+  not_openable: "The file is not a zip that can be read."
+};
+var OwWorldFileError = class extends Error {
+  constructor(reason, message = MESSAGES[reason]) {
+    super(message);
+    this.name = "OwWorldFileError";
+    this.reason = reason;
+  }
+};
+function isSafePath(path) {
+  if (!path || path.includes("\\") || path.startsWith("/") || /^[a-zA-Z]:/.test(path)) return false;
+  return path.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+function isJunk(path) {
+  return path.split("/").some((seg) => seg === "__MACOSX" || seg === ".DS_Store" || seg === "Thumbs.db");
+}
+function parseWorld(data) {
+  let meta;
+  try {
+    meta = JSON.parse(new TextDecoder().decode(data));
+  } catch {
+    throw new OwWorldFileError("not_a_world");
+  }
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) throw new OwWorldFileError("not_a_world");
+  const id = meta.id;
+  if (typeof id !== "string" || !id.trim()) throw new OwWorldFileError("not_a_world");
+  return meta;
+}
+function withoutLink(data, meta) {
+  if (!("api" in meta)) return { data, world: meta };
+  const { api: _link, ...rest } = meta;
+  return { data: new TextEncoder().encode(JSON.stringify(rest, null, 2) + "\n"), world: rest };
+}
+function readWorldFile(bytes, opts = {}) {
+  const maxBytes = opts.maxBytes ?? WORLD_FILE_MAX_BYTES;
+  const maxEntries = opts.maxEntries ?? WORLD_FILE_MAX_ENTRIES;
+  let declared = 0;
+  let count = 0;
+  let refusal = null;
+  let raw;
+  try {
+    raw = unzipSync(bytes, {
+      filter: (file) => {
+        if (refusal) return false;
+        if (file.name.endsWith("/")) return false;
+        if (!isSafePath(file.name)) {
+          refusal = "unsafe_path";
+          return false;
+        }
+        if (isJunk(file.name)) return false;
+        count++;
+        declared += file.originalSize;
+        if (count > maxEntries) {
+          refusal = "too_many";
+          return false;
+        }
+        if (declared > maxBytes) {
+          refusal = "too_big";
+          return false;
+        }
+        return true;
+      }
+    });
+  } catch {
+    throw new OwWorldFileError(refusal ?? "not_openable");
+  }
+  if (refusal) throw new OwWorldFileError(refusal);
+  const names = Object.keys(raw);
+  if (names.reduce((n, k) => n + raw[k].length, 0) > maxBytes) throw new OwWorldFileError("too_big");
+  const nameSet = new Set(names);
+  for (const n of names) {
+    const segs = n.split("/");
+    for (let i = 1; i < segs.length; i++) {
+      if (nameSet.has(segs.slice(0, i).join("/"))) throw new OwWorldFileError("unsafe_path");
+    }
+  }
+  let prefix;
+  if (nameSet.has(WORLD_FILE)) {
+    prefix = "";
+  } else {
+    const tops = new Set(names.map((n) => n.includes("/") ? n.split("/")[0] + "/" : n));
+    const worldTops = [...tops].filter((t) => t.endsWith("/") && nameSet.has(`${t}${WORLD_FILE}`));
+    if (worldTops.length === 0) throw new OwWorldFileError("not_a_world");
+    if (worldTops.length > 1 || tops.size > 1) throw new OwWorldFileError("more_than_one");
+    prefix = worldTops[0];
+  }
+  const worldName = `${prefix}${WORLD_FILE}`;
+  if (names.some((n) => n !== worldName && n.endsWith(`/${WORLD_FILE}`))) throw new OwWorldFileError("more_than_one");
+  const parsed = withoutLink(raw[worldName], parseWorld(raw[worldName]));
+  const files = [];
+  for (const n of names) {
+    const path = n.slice(prefix.length);
+    if (opts.skip?.(path)) continue;
+    files.push({ path, data: n === worldName ? parsed.data : raw[n] });
+  }
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const name = parsed.world.name;
+  return {
+    worldId: parsed.world.id,
+    name: typeof name === "string" ? name : "",
+    world: parsed.world,
+    files
+  };
+}
+function writeWorldFile(files, topDir) {
+  if (!isSafePath(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
+  const input = {};
+  let sawWorld = false;
+  for (const f of files) {
+    if (!isSafePath(f.path)) throw new OwWorldFileError("unsafe_path");
+    const key = `${topDir}/${f.path}`;
+    if (key in input) throw new OwWorldFileError("unsafe_path", `The path ${f.path} is listed twice.`);
+    let data = f.data;
+    if (f.path === WORLD_FILE) {
+      data = withoutLink(data, parseWorld(data)).data;
+      sawWorld = true;
+    }
+    input[key] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0 }];
+  }
+  if (!sawWorld) throw new OwWorldFileError("not_a_world");
+  return zipSync(input);
+}
+
 // src/token-resource.ts
 var TokenResource = class {
   constructor(client) {
@@ -1488,9 +1650,13 @@ export {
   ONLYWORLDS_VERSION,
   OwApiError,
   OwNetworkError,
+  OwPreconditionFailedError,
   OwV2Client,
+  OwWorldFileError,
   SPATIAL_TYPES,
   TokenResource,
+  WORLD_FILE_MAX_BYTES,
+  WORLD_FILE_MAX_ENTRIES,
   detectKeyKind,
   elementColor,
   errorFromResponse,
@@ -1500,5 +1666,7 @@ export {
   isDemoKey,
   kindCanWrite,
   parseErrorEnvelope,
-  pinExpectation
+  pinExpectation,
+  readWorldFile,
+  writeWorldFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.8.1",
+  "version": "4.10.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {
@@ -60,5 +60,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3"
   }
 }