@onlyworlds/sdk 4.9.0 → 4.10.0

package/AGENTS.md

@@ -40,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,28 @@ 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

package/README.md

@@ -135,6 +135,22 @@ try {
 
 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. A write sent with `ifMatch` that found the element moved throws `OwPreconditionFailedError` (412, `err.isPreconditionFailed`), an `OwApiError` that also carries `current`.

package/dist/index.d.ts

@@ -2459,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
  *
@@ -2743,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, OwPreconditionFailedError, 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

@@ -1333,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) {
@@ -1518,8 +1652,11 @@ export {
   OwNetworkError,
   OwPreconditionFailedError,
   OwV2Client,
+  OwWorldFileError,
   SPATIAL_TYPES,
   TokenResource,
+  WORLD_FILE_MAX_BYTES,
+  WORLD_FILE_MAX_ENTRIES,
   detectKeyKind,
   elementColor,
   errorFromResponse,
@@ -1529,5 +1666,7 @@ export {
   isDemoKey,
   kindCanWrite,
   parseErrorEnvelope,
-  pinExpectation
+  pinExpectation,
+  readWorldFile,
+  writeWorldFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.9.0",
+  "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"
   }
 }