@onlyworlds/sdk 4.6.0 → 4.7.0

package/AGENTS.md

@@ -21,7 +21,7 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
   responses, far cheaper than tool-schema reasoning.
 - Live exploration of a user's world from a chat/agent context → the **MCP server** at
-  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools).
+  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 12 tools).
 
 **Wire facts that bite** (full details in README):
 - Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).

package/CHANGELOG.md

@@ -5,13 +5,31 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.6.0] — 2026-10-06 (staged, not published)
+## [4.7.0] — 2026-10-08
+
+### Added
+- **`OwApiError.isResyncRequired`**: 409 `resync_required` from `/changes`. Guests can follow the
+  feed since keel D79; when a guest's view or a key's role changes, its stored cursor is refused. Drop
+  it, walk from zero, and replace the local copy rather than merging.
+
+### Documented
+- `uploadImage` accepts webp, png, jpeg and avif. 4.6.0's JSDoc and README also listed gif, which
+  the edge refuses (415 `unsupported_type`); checked against the Worker's type table.
+- `changes()`: the old rewind rule compared a stored cursor with `head`, which an opaque cursor
+  cannot do; replaced with the reset rule (`isResyncRequired`).
+- The doc comments of `OwClientConfig`, `create` and `uploadImage` are written for users: internal
+  ruling numbers and test-harness notes are gone, and each opens with what the option or method does.
+  The docs site's TypeScript reference is generated from these comments.
+
+## [4.6.0] — 2026-10-06
+
+Published from `e198298` (tag `v4.6.0`); the tarball was checked against a build of that commit.
 
 Includes 4.5.1's documentation fixes: 4.5.1 was staged and never published.
 
 ### Added
-- **`uploadImage(image, { key?, ticket? })`**: upload one image (webp, png, jpeg, avif, gif;
-  never SVG) and get its permanent public URL. Two requests: a ticket from keel
+- **`uploadImage(image, { key?, ticket? })`**: upload one image (webp, png, jpeg, avif;
+  never SVG; 4.6.0's docs also said gif, which the edge refuses with 415) and get its permanent public URL. Two requests: a ticket from keel
   (`POST /media/ticket`), then the bytes straight to the edge at the ticket's `upload_url`
   (keel never sees them). Only the ticket goes to the edge, never the API key or PIN. An image
   larger than the ticket's `max_bytes` throws 413 `too_large` before anything is sent; the edge's

package/README.md

@@ -98,8 +98,8 @@ await writer.patch('character', id, { image_url: image.url });
 ```
 
 Two requests: a single-use ticket from keel, then the bytes straight to the edge (keel never
-sees them, and the edge never sees your key). webp, png, jpeg, avif or gif, read from the
-bytes; never SVG. Each ticket counts toward the world's daily limit and the account's image
+sees them, and the edge never sees your key). webp, png, jpeg or avif (never SVG or gif), read from the
+bytes. Each ticket counts toward the world's daily limit and the account's image
 storage. To upload yourself (for a progress bar), take `createMediaTicket()` and POST the bytes to
 its `upload_url` with `Authorization: Bearer <ticket>`.
 
@@ -151,7 +151,7 @@ const status = await tokens.getStatus();
 
 For **known, deterministic operations** (CRUD, sync, bulk) use this SDK — typed calls, no
 tool-schema overhead. For **live exploration of a user's world from a chat/agent context**, use
-the MCP server at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools;
+the MCP server at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 12 tools;
 unaffected by SDK versioning).
 
 ## License

package/dist/index.d.ts

@@ -2000,27 +2000,26 @@ interface ListParams {
     filter?: Record<string, string | number | boolean>;
 }
 interface OwClientConfig {
-    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 10-digit legacy key. */
+    /** The key: an ow_w_ (write) or ow_r_ (read) world key, an ow_a_ account token (sent as a Bearer token, for the account routes), or a 10-digit legacy key. */
     apiKey: string;
     /**
-     * Optional. Required for writes when the world has a PIN, and for legacy-key
-     * reads of private worlds. Prefixed keys read PIN-less. String, not number --
-     * '0123' !== 123.
+     * The PIN, needed for writes when the world has one, and for legacy-key reads of private worlds.
+     * Prefixed keys read without a PIN. A string, not a number: '0123' !== 123.
      */
     apiPin?: string;
-    /** Default: https://www.onlyworlds.com/api/v2 */
+    /** The API's base URL, default https://www.onlyworlds.com/api/v2. */
     baseUrl?: string;
     /**
-     * Page size for element lists. Default 100 (server default; max 1000).
-     * Deliberately visible in config: page size is a citizenship property.
+     * Page size for element lists, default 100 (the server's default; at most 1000).
+     * It is in the config on purpose: page size decides the load a client puts on the server.
      */
     pageSize?: number;
     /**
-     * Page size for /changes pulls. Default 100. Live precedents: Obsidian 100,
-     * Atlas 250, MCP 25. /changes is the platform's heaviest route -- be polite.
+     * Page size for /changes pulls, default 100. Tools in use pick 25 to 250; the change feed
+     * is the platform's heaviest route, so keep it modest.
      */
     changesPageSize?: number;
-    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
+    /** A fetch implementation to use instead of globalThis.fetch (for tests and other runtimes). */
     fetch?: typeof globalThis.fetch;
 }
 
@@ -2079,6 +2078,13 @@ declare class OwApiError extends Error {
      * per-item slot `{status: 409, error: {code: 'id_conflict'}}` — check the slot.
      */
     get isIdConflict(): boolean;
+    /**
+     * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
+     * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
+     * cursor, walk again from the start, and REPLACE the local copy rather than merging into
+     * it: a guest never receives delete ops, so only the replace removes what it no longer sees.
+     */
+    get isResyncRequired(): boolean;
     /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
     get isBusy(): boolean;
     /**
@@ -2175,11 +2181,11 @@ declare class OwV2Client {
     /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
     get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
     /**
-     * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 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.
+     * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
+     * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
+     * the same element instead of creating a second one. You may still supply your own id.
      * `name` is the one required field, and required means the key is present: `''` and
-     * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
+     * `null` are accepted and stored as `''` (nameless Markers exist).
      */
     create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
         idempotencyKey?: string;
@@ -2223,10 +2229,12 @@ declare class OwV2Client {
     }): Promise<OwBulkResponse>;
     /**
      * GET /changes -- one page of the world's ordered change feed.
-     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+     * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
+     * another shape than everyone else's).
      * 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.
+     * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
+     * view changed (a guest's, or its role): drop the cursor, walk from zero, and
+     * replace the local copy rather than merging into it.
      * Citizenship: heaviest route on the platform; default page size is polite.
      */
     changes(opts?: {
@@ -2254,12 +2262,12 @@ declare class OwV2Client {
      */
     createMediaTicket(): Promise<OwMediaTicket>;
     /**
-     * Upload one image and get its permanent public URL: a ticket from keel, then the
-     * bytes straight to the edge (keel never sees them). Pass a ticket from
+     * Upload one image and get its permanent public URL: a ticket from the API, then the
+     * bytes straight to the media edge (the API never sees them). Pass a ticket from
      * createMediaTicket() to use it instead of fetching one. Returns the edge's 201;
      * set `url` as an element's `image_url` yourself (`patch(type, id, { image_url })`).
      *
-     * webp, png, jpeg, avif or gif, read from the bytes (never SVG). `key` names the
+     * webp, png, jpeg or avif, read from the bytes (never SVG or gif). `key` names the
      * object (it must start with the ticket's `prefix`; without it the edge picks one).
      * An image larger than the ticket's `max_bytes` throws 413 `too_large` before any
      * byte is sent. The edge's refusals arrive as OwApiError with its code: 401

package/dist/index.js

@@ -35,6 +35,15 @@ var OwApiError = class extends Error {
   get isIdConflict() {
     return this.status === 409 && this.code === "id_conflict";
   }
+  /**
+   * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
+   * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
+   * cursor, walk again from the start, and REPLACE the local copy rather than merging into
+   * it: a guest never receives delete ops, so only the replace removes what it no longer sees.
+   */
+  get isResyncRequired() {
+    return this.status === 409 && this.code === "resync_required";
+  }
   /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
   get isBusy() {
     return this.status === 503 && this.code === "server_busy";
@@ -188,11 +197,11 @@ var OwV2Client = class {
     return this.request("GET", `/${type}/${id}/`, { query });
   }
   /**
-   * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 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.
+   * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
+   * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
+   * the same element instead of creating a second one. You may still supply your own id.
    * `name` is the one required field, and required means the key is present: `''` and
-   * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
+   * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
     const body = sanitizePayload(element);
@@ -260,10 +269,12 @@ var OwV2Client = class {
   // -- Changes feed --------------------------------------------------------
   /**
    * GET /changes -- one page of the world's ordered change feed.
-   * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+   * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
+   * another shape than everyone else's).
    * 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.
+   * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
+   * view changed (a guest's, or its role): drop the cursor, walk from zero, and
+   * replace the local copy rather than merging into it.
    * Citizenship: heaviest route on the platform; default page size is polite.
    */
   async changes(opts = {}) {
@@ -300,12 +311,12 @@ var OwV2Client = class {
     return this.request("POST", "/media/ticket");
   }
   /**
-   * Upload one image and get its permanent public URL: a ticket from keel, then the
-   * bytes straight to the edge (keel never sees them). Pass a ticket from
+   * Upload one image and get its permanent public URL: a ticket from the API, then the
+   * bytes straight to the media edge (the API never sees them). Pass a ticket from
    * createMediaTicket() to use it instead of fetching one. Returns the edge's 201;
    * set `url` as an element's `image_url` yourself (`patch(type, id, { image_url })`).
    *
-   * webp, png, jpeg, avif or gif, read from the bytes (never SVG). `key` names the
+   * webp, png, jpeg or avif, read from the bytes (never SVG or gif). `key` names the
    * object (it must start with the ticket's `prefix`; without it the edge picks one).
    * An image larger than the ticket's `max_bytes` throws 413 `too_large` before any
    * byte is sent. The edge's refusals arrive as OwApiError with its code: 401

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {