@onlyworlds/sdk 4.5.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).
@@ -31,8 +31,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - 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,
   `param: extensions`).
-- List filters: only `name__icontains`, `supertype` and `subtype` are built. Any other
-  filter key — and `?ordering=` — returns 422 naming it. Filter or sort client-side.
+- List filters: `name` (exact), `name__icontains`, `supertype`, `subtype`, and
+  `characters=<id>` on types with a `characters` link. Any other filter key — and
+  `?ordering=` — returns 422 naming the accepted ones. Sort client-side.
+- 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.
 - 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,7 +5,60 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.5.0] — 2026-10-04 (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;
+  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
+  refusals (`ticket_used`, `ticket_expired`, `bad_key`, `exists`, `unsupported_type`, ...) arrive
+  as `OwApiError` with their code. Set the returned `url` as an element's `image_url` yourself.
+  Checked live on 2026-10-06: one upload through keel's ticket to the edge (201), and the same
+  ticket again refused with 401 `ticket_used` (Keel #59).
+- **`createMediaTicket()`**: the first step alone, for callers that upload themselves (progress
+  bars, say). Types `OwMediaTicket` and `OwUploadedImage`.
+
+### Documented
+- `ListParams.filter` lists what keel accepts now: exact `name`, and `characters=<id>` on every
+  type with a `characters` link (keel D76d).
+
+## [4.5.1] — 2026-10-05 (never published; shipped in 4.6.0)
+
+Docs only: no code path changes.
+
+### Documented
+- **`isOwnerOnly`'s JSDoc in 4.5.0 was wrong about who sees `owner_only`.** It said owners and
+  co-builders never see it. A member key, a co-builder's too, gets it on `PATCH /world`; only the
+  owner's key is exempt (keel spec section 9; confirmed from keel's `patch_world` by Skeld,
+  2026-10-04).
+- **`world_gone` is reserved.** `OwAuthErrorCode` and `isAuthError` still carry it, but keel never
+  emits it: a deleted world's keys are deleted with it, so the key answers 401 `invalid_credentials`
+  (Skeld, 2026-10-04; keel spec section 2, T6b). Found by the wire gate reading the SDK's own
+  built file for the codes it keys on.
+
+## [4.5.0] — 2026-10-04
 
 What the staging write probes found on the wire (Python package, 2026-10-04): one new getter, and
 three behaviours the server has always had that no client doc said. Additive; nothing is removed.

package/README.md

@@ -90,6 +90,19 @@ if (res.errors) {
 // still say 201 (keel's counterfactual 201s): do not record those ids as created.
 ```
 
+## Images
+
+```typescript
+const image = await writer.uploadImage(file);             // a Blob, File, ArrayBuffer or Uint8Array
+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 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>`.
+
 ## Sync
 
 ```typescript
@@ -138,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

@@ -1947,6 +1947,41 @@ interface OwLinkEdit {
     add?: string[];
     remove?: string[];
 }
+/**
+ * POST /media/ticket's 201: a short-lived, single-use permission to upload one image
+ * into this world's prefix. keel never sees the bytes; the edge at `upload_url` does.
+ */
+interface OwMediaTicket {
+    /** Opaque: send it to `upload_url` as `Authorization: Bearer <ticket>`, as is. */
+    ticket: string;
+    /** Where the image goes (https://upload.onlyworlds.com/v1/upload on production). */
+    upload_url: string;
+    /** `u/<world_id>/`: every upload with this ticket lands under it. */
+    prefix: string;
+    /** The most this ticket accepts: the per-image limit, or what the account has left, whichever is smaller. */
+    max_bytes: number;
+    /** Unix seconds after which the edge refuses the ticket. */
+    exp: number;
+    /** Always 1: one ticket, one upload. */
+    uses: number;
+    /** Who answers for the upload; the edge copies it onto the stored object. */
+    issued_to: {
+        account: string | null;
+        membership: string | null;
+    };
+}
+/** The edge's 201 for one upload. Put `url` in an element's `image_url`. */
+interface OwUploadedImage {
+    /** The permanent public URL (https://media.onlyworlds.com/<key>). */
+    url: string;
+    /** The object key, under the ticket's `prefix`. */
+    key: string;
+    bytes: number;
+    /** The MIME type the edge read from the bytes (never from a header or a file name). */
+    type: string;
+    etag: string;
+    [k: string]: unknown;
+}
 interface ListParams {
     limit?: number;
     cursor?: string;
@@ -1955,35 +1990,36 @@ interface ListParams {
     /** Sparse include-set of field names. */
     fields?: string[];
     /**
-     * Accepted: `name__icontains`, `supertype`, `subtype`. Any other key 422s
-     * server-side, which names the typo -- the client passes keys through
-     * unchecked and lets the platform say so. (`__in`, `__gte`, `__lte` and
+     * Accepted: `name` (exact), `name__icontains`, `supertype`, `subtype`, and
+     * `characters=<id>` (contains) on every type with a `characters` link (at schema
+     * 0.30.1: collective, construct, event, narrative, relation, title; keel D76d). Any other key 422s
+     * server-side with the list of filters in the message -- the client passes keys
+     * through unchecked and lets the platform say so. (`__in`, `__gte`, `__lte` and
      * `__isnull` are designed in keel's spec but not built; `ordering` 422s too.)
      */
     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;
 }
 
@@ -1997,7 +2033,12 @@ interface OwClientConfig {
  * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
  * surfaced on the thrown error.
  */
-/** Auth codes are distinguishable by design; client recovery UX differs per code. */
+/**
+ * Auth codes are distinguishable by design; client recovery UX differs per code.
+ * `world_gone` is RESERVED: keel's spec promises it but the server never emits it (a deleted
+ * world's keys go with it, so the key reads as unknown: 401 `invalid_credentials`). Kept so
+ * the client is ready if keel ever remembers deleted worlds' key hashes.
+ */
 type OwAuthErrorCode = 'invalid_credentials' | 'key_revoked' | 'world_gone';
 declare class OwApiError extends Error {
     readonly status: number;
@@ -2037,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;
     /**
@@ -2047,9 +2095,10 @@ declare class OwApiError extends Error {
      */
     get isNotAuthor(): boolean;
     /**
-     * A contributor tried a world-level change: `patchWorld`, or publishing a show page
-     * (403 `owner_only`, keel D72 membership phase 2). Retrying will not help; only the
-     * owner may. Owners and co-builders never see it.
+     * A member key tried what only the owner may do: `patchWorld`, even with a co-builder's
+     * key (403 `owner_only`, keel D72; sharing's publish, republish and revoke answer
+     * contributors and guests with the same code). Retrying will not help. The owner's own
+     * key never sees it.
      */
     get isOwnerOnly(): boolean;
 }
@@ -2132,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;
@@ -2180,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?: {
@@ -2199,6 +2250,36 @@ declare class OwV2Client {
         cursor: string;
         head: number;
     }>;
+    /**
+     * POST /media/ticket -- permission to upload ONE image into this world (a write
+     * key and its PIN; no body). Short-lived (`exp`), single-use, counted toward the
+     * world's daily limit. Use it directly to upload yourself (for progress, say):
+     * POST the bytes to `upload_url` with `Authorization: Bearer <ticket>`. Otherwise
+     * call uploadImage(), which does both steps. Refusals: 403 `storage_full` (the
+     * account's image storage is used up), 429 `quota_exceeded` (the world's daily
+     * limit; Retry-After) as well as the wrong-PIN 429 `rate_limited`, 503
+     * `media_unavailable`.
+     */
+    createMediaTicket(): Promise<OwMediaTicket>;
+    /**
+     * 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 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
+     * `ticket_expired` / `ticket_used` / `ticket_invalid`, 400 `bad_key`, 409 `exists`,
+     * 413 `too_large`, 415 `unsupported_type`, 502 `write_failed` (nothing stored; the
+     * ticket is still unspent). A ticket is spent once the upload succeeds: a retry
+     * needs a new one.
+     */
+    uploadImage(image: Blob | ArrayBuffer | ArrayBufferView, opts?: {
+        key?: string;
+        ticket?: OwMediaTicket;
+    }): Promise<OwUploadedImage>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -2573,4 +2654,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, OwNetworkError, type OwPage, 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, 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 };

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";
@@ -49,9 +58,10 @@ var OwApiError = class extends Error {
     return this.status === 403 && this.code === "not_author";
   }
   /**
-   * A contributor tried a world-level change: `patchWorld`, or publishing a show page
-   * (403 `owner_only`, keel D72 membership phase 2). Retrying will not help; only the
-   * owner may. Owners and co-builders never see it.
+   * A member key tried what only the owner may do: `patchWorld`, even with a co-builder's
+   * key (403 `owner_only`, keel D72; sharing's publish, republish and revoke answer
+   * contributors and guests with the same code). Retrying will not help. The owner's own
+   * key never sees it.
    */
   get isOwnerOnly() {
     return this.status === 403 && this.code === "owner_only";
@@ -187,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);
@@ -259,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 = {}) {
@@ -284,6 +296,58 @@ var OwV2Client = class {
     } while (page.has_more);
     return { cursor: page.cursor, head: page.head };
   }
+  // -- Images ---------------------------------------------------------------
+  /**
+   * POST /media/ticket -- permission to upload ONE image into this world (a write
+   * key and its PIN; no body). Short-lived (`exp`), single-use, counted toward the
+   * world's daily limit. Use it directly to upload yourself (for progress, say):
+   * POST the bytes to `upload_url` with `Authorization: Bearer <ticket>`. Otherwise
+   * call uploadImage(), which does both steps. Refusals: 403 `storage_full` (the
+   * account's image storage is used up), 429 `quota_exceeded` (the world's daily
+   * limit; Retry-After) as well as the wrong-PIN 429 `rate_limited`, 503
+   * `media_unavailable`.
+   */
+  async createMediaTicket() {
+    return this.request("POST", "/media/ticket");
+  }
+  /**
+   * 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 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
+   * `ticket_expired` / `ticket_used` / `ticket_invalid`, 400 `bad_key`, 409 `exists`,
+   * 413 `too_large`, 415 `unsupported_type`, 502 `write_failed` (nothing stored; the
+   * ticket is still unspent). A ticket is spent once the upload succeeds: a retry
+   * needs a new one.
+   */
+  async uploadImage(image, opts = {}) {
+    const ticket = opts.ticket ?? await this.createMediaTicket();
+    const size = typeof Blob !== "undefined" && image instanceof Blob ? image.size : image.byteLength;
+    if (size > ticket.max_bytes) {
+      throw new OwApiError(
+        413,
+        "too_large",
+        `Image is ${size} bytes; this ticket accepts at most ${ticket.max_bytes}. Nothing was sent.`,
+        null,
+        { error: "too_large", max_bytes: ticket.max_bytes, got: size }
+      );
+    }
+    const headers = { Authorization: `Bearer ${ticket.ticket}` };
+    if (opts.key) headers["X-Key"] = opts.key;
+    let res;
+    try {
+      res = await this.fetchImpl(ticket.upload_url, { method: "POST", headers, body: image });
+    } catch (cause) {
+      throw new OwNetworkError(`OnlyWorlds image upload failed: POST ${ticket.upload_url}`, cause);
+    }
+    if (!res.ok) throw await errorFromResponse(res);
+    return await res.json();
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0

package/package.json

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