@onlyworlds/sdk 4.5.0 → 4.6.0

package/AGENTS.md

@@ -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,42 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.5.0] — 2026-10-04 (staged, not published)
+## [4.6.0] — 2026-10-06 (staged, not published)
+
+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
+  (`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, avif or gif, read from the
+bytes; never SVG. 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

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,9 +1990,11 @@ 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>;
@@ -1997,7 +2034,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;
@@ -2047,9 +2089,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;
 }
@@ -2199,6 +2242,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 keel, then the
+     * bytes straight to the edge (keel 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
+     * 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 +2646,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

@@ -49,9 +49,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";
@@ -284,6 +285,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 keel, then the
+   * bytes straight to the edge (keel 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
+   * 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.6.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {