@onlyworlds/sdk 4.4.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,60 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.4.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.
+
+### Added
+- **`OwApiError.isOwnerOnly`**: 403 `owner_only`, a contributor attempting a world-level change
+  (`patchWorld`, publishing a show page). Owners and co-builders never see it. keel's OpenAPI
+  document does not name the code yet (Skeld has that to close); the wire returns it.
+
+### Documented
+- **An atomic `/bulk` rollback still returns 201 slots** for the items that would have
+  succeeded, with the ids and timestamps they would have had (keel spec: "counterfactual 201s").
+  After `atomic: true` with `errors: true`, nothing was written. On `bulk()`, `OwBulkItemResult`
+  and the README.
+- **`name` is required as a key only**: `''` and `null` are accepted and stored as `''` (keel
+  ruling 2026-09-28, spec §6; nameless Markers exist). On `create()` and the README.
+
+## [4.4.0] — 2026-10-04
 
 Membership, as far as the server has shipped it: who created an element, and the refusal a
 contributor meets on someone else's. Additive; nothing is removed or narrows.

package/README.md

@@ -45,6 +45,8 @@ const location = await writer.create('location', {
   name: 'Dragon Peak',
   description: 'A treacherous mountain peak where dragons nest',
 }); // id minted client-side when omitted (retries stay idempotent)
+// name is the one required field, and required means the key is present:
+// '' and null are accepted and stored as '' (nameless Markers exist).
 
 const dragon = await writer.create('creature', {
   name: 'Vorrath the Ember-Scaled',
@@ -84,8 +86,23 @@ if (res.errors) {
   }
 }
 // Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
+// After a failed atomic batch NOTHING was written, but the slots that would have succeeded
+// 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

@@ -1912,6 +1912,9 @@ interface OwBulkItem {
  * created_at/updated_at, error slots carry an OwErrorBody under `error`.
  * A contributor's write on someone else's element fails in its slot as
  * `{status: 403, error: {code: 'not_author'}}` (keel D72), never as a thrown error.
+ * After an `atomic: true` request with `errors` true NOTHING was written, yet the slots of
+ * the items that would have succeeded still say 201 (keel's "counterfactual 201s"): do not
+ * record their ids as created.
  */
 interface OwBulkItemResult {
     status: number;
@@ -1944,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;
@@ -1952,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>;
@@ -1994,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;
@@ -2043,6 +2088,13 @@ declare class OwApiError extends Error {
      * slot `{status: 403, error: {code: 'not_author'}}`. Owners and co-builders never see it.
      */
     get isNotAuthor(): boolean;
+    /**
+     * 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;
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2126,6 +2178,8 @@ declare class OwV2Client {
      * 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.
+     * `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).
      */
     create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
         idempotencyKey?: string;
@@ -2159,6 +2213,9 @@ declare class OwV2Client {
      * Success slots echo server-authoritative timestamps: set your sync baseline
      * from this response alone. When an idempotencyKey is replayed, the returned
      * response carries wasReplay:true (read from the Idempotent-Replay header).
+     * After an atomic:true request with errors:true NOTHING was written, yet the slots of
+     * the items that would have succeeded still say 201 with the ids and timestamps they
+     * would have had (keel's "counterfactual 201s"): do not record those ids as created.
      */
     bulk(items: OwBulkItem[], opts?: {
         atomic?: boolean;
@@ -2185,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
@@ -2559,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

@@ -48,6 +48,15 @@ var OwApiError = class extends Error {
   get isNotAuthor() {
     return this.status === 403 && this.code === "not_author";
   }
+  /**
+   * 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";
+  }
 };
 var OwNetworkError = class extends Error {
   constructor(message, cause) {
@@ -182,6 +191,8 @@ var OwV2Client = class {
    * 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.
+   * `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).
    */
   async create(type, element, opts = {}) {
     const body = sanitizePayload(element);
@@ -231,6 +242,9 @@ var OwV2Client = class {
    * Success slots echo server-authoritative timestamps: set your sync baseline
    * from this response alone. When an idempotencyKey is replayed, the returned
    * response carries wasReplay:true (read from the Idempotent-Replay header).
+   * After an atomic:true request with errors:true NOTHING was written, yet the slots of
+   * the items that would have succeeded still say 201 with the ids and timestamps they
+   * would have had (keel's "counterfactual 201s"): do not record those ids as created.
    */
   async bulk(items, opts = {}) {
     const body = {
@@ -271,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.4.0",
+  "version": "4.6.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {