@onlyworlds/sdk 4.7.3 → 4.8.0

package/AGENTS.md

@@ -1,62 +1,63 @@
-# For AI agents using @onlyworlds/sdk
-
-**Current as of**: SDK **4.x** · schema-dist **v0.31.0-dist.19** (canonical 00.31.00).
-This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
-re-read against it, the check fails rather than letting this document rot quietly.
-
-**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
-every type, every field with its meaning, link directions, families, icons, display sections.
-It is generated from the same canonical YAML as the types, so it cannot drift.
-
-**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
-plus the canonical constants (element types, icons, colour families, field schema).
-OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
-
-**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
-interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
-against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is not in
-4.x — it was removed at 4.0.0 and lives only in 3.x. Do not build new work on it.
-
-**SDK vs MCP server — pick correctly**:
-- 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, 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).
-- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
-- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
-- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
-- 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: `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
-  `created_at`; `change_seq` is last-write order, not creation.
-  A create with an id that already exists, or a PUT whose id belongs to **another world**,
-  returns 409 `id_conflict` (`err.isIdConflict`; retrying won't help). `/bulk` never throws:
-  check each slot for `status: 409` with `error.code: 'id_conflict'`. A different 409, `idempotency_error`, means an
-  Idempotency-Key was reused with another body (`err.isIdempotencyConflict`).
-- Under load keel answers 503 `server_busy` with `Retry-After` (`err.isBusy`, `err.retryAfter`
-  in seconds). The client does not retry for you; back off and retry yourself. Works the same
-  in browsers.
-- `created_by` rides every element read: the id of the membership that created it, `null` for
-  the world's owner and for anything made before memberships existed. It is read-only; a write
-  body that carries it has it dropped, never an error. A **contributor** can change only what
-  they created: anything else is 403 `not_author` (`err.isNotAuthor`; retrying will not help).
-  `/bulk` reports it per slot, not as a throw.
-- A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
-  Slice strings by code point, not by UTF-16 unit.
-- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
-  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
-
-**Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
-primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
-test credentials against real data.
+# For AI agents using @onlyworlds/sdk
+
+**Current as of**: SDK **4.x** · schema-dist **v0.31.0-dist.19** (canonical 00.31.00).
+This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
+re-read against it, the check fails rather than letting this document rot quietly.
+
+**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
+every type, every field with its meaning, link directions, families, icons, display sections.
+It is generated from the same canonical YAML as the types, so it cannot drift.
+
+**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
+plus the canonical constants (element types, icons, colour families, field schema).
+OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
+
+**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
+interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
+against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is not in
+4.x — it was removed at 4.0.0 and lives only in 3.x. Do not build new work on it.
+
+**SDK vs MCP server — pick correctly**:
+- 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, 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).
+- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
+- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
+- 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: `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. `removeImage(urlOrKey)`
+  takes one back (its uploader or the world's owner); it leaves `image_url` on elements as is.
+- 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
+  `created_at`; `change_seq` is last-write order, not creation.
+  A create with an id that already exists, or a PUT whose id belongs to **another world**,
+  returns 409 `id_conflict` (`err.isIdConflict`; retrying won't help). `/bulk` never throws:
+  check each slot for `status: 409` with `error.code: 'id_conflict'`. A different 409, `idempotency_error`, means an
+  Idempotency-Key was reused with another body (`err.isIdempotencyConflict`).
+- Under load keel answers 503 `server_busy` with `Retry-After` (`err.isBusy`, `err.retryAfter`
+  in seconds). The client does not retry for you; back off and retry yourself. Works the same
+  in browsers.
+- `created_by` rides every element read: the id of the membership that created it, `null` for
+  the world's owner and for anything made before memberships existed. It is read-only; a write
+  body that carries it has it dropped, never an error. A **contributor** can change only what
+  they created: anything else is 403 `not_author` (`err.isNotAuthor`; retrying will not help).
+  `/bulk` reports it per slot, not as a throw.
+- A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
+  Slice strings by code point, not by UTF-16 unit.
+- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
+  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
+
+**Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
+primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
+test credentials against real data.

package/CHANGELOG.md

@@ -5,6 +5,21 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.8.0] — 2026-10-10
+
+### Added
+- **`removeImage(keyOrUrl, { ticket? })`**: removes one uploaded image. A removal ticket from
+  keel (`POST /media/remove-ticket`, keel D91), then the removal at the ticket's `remove_url`
+  with the ticket only, never the API key. Takes the object key or the whole `image_url`. The
+  image's uploader or the world's owner key may remove it; the bytes go back to the uploader's
+  storage. Elements keep their `image_url`: clear it yourself.
+- **`createRemovalTicket(key)`** and the types **`OwRemovalTicket`** (`ticket`, `remove_url`,
+  `exp` in unix seconds, `key`, `referenced`: how many elements still show the image) and
+  **`OwRemovedImage`** (`removed`, `bytes`, `cache`). Refusals arrive as `OwApiError`: keel's
+  `permission_error`, `not_found`, `removal_in_flight` and `upload_pending` (both 409 with
+  Retry-After); the edge's `ticket_expired`, `ticket_used`, `ticket_invalid`, `not_removable`,
+  `remove_failed`.
+
 ## [4.7.3] — 2026-10-10
 
 ### Changed

package/README.md

@@ -101,6 +101,13 @@ await writer.patch('character', id, { image_url: image.url });
 
 The SDK asks the API for a single-use ticket, then sends the bytes straight to the upload host, which never sees your key. webp, png, jpeg or avif (no SVG or gif), up to 15 MB. Each upload counts toward the world's daily limit and the account's storage. To upload yourself (for a progress bar), call `createMediaTicket()` and POST the bytes to its `upload_url` with `Authorization: Bearer <ticket>`.
 
+```typescript
+await writer.removeImage(image.url); // the image_url, or its object key
+await writer.patch('character', id, { image_url: null });
+```
+
+The image's uploader or the world's owner can remove an uploaded image; the space goes back to the uploader's storage. Removal leaves elements as they are, so clear their `image_url` yourself (`createRemovalTicket(key).referenced` says how many still show it). A copy the network already holds can keep answering for a while.
+
 ## Sync
 
 ```typescript

package/dist/index.d.ts

@@ -1970,6 +1970,37 @@ interface OwMediaTicket {
         membership: string | null;
     };
 }
+/**
+ * POST /media/remove-ticket's 200: a short-lived, single-use permission to remove one
+ * image. keel issues it to the image's uploader or the world's owner key; the edge at
+ * `remove_url` does the removal.
+ */
+interface OwRemovalTicket {
+    /** Opaque: send it to `remove_url` as `Authorization: Bearer <ticket>`, as is. */
+    ticket: string;
+    /** Where the removal goes: the upload host's /v1/remove (https://upload.onlyworlds.com/v1/remove on production). */
+    remove_url: string;
+    /** Unix seconds after which the edge refuses the ticket (10 minutes after issue). */
+    exp: number;
+    /** The object key the ticket removes. */
+    key: string;
+    /** How many of the world's elements show the image. Removal does not change them: clear their `image_url` yourself. */
+    referenced: number;
+}
+/** The edge's 200 for one removal. */
+interface OwRemovedImage {
+    /** The object key that was removed. */
+    removed: string;
+    /** The bytes given back to the uploading account's storage. */
+    bytes: number;
+    /**
+     * `may_linger`: copies the network or a browser already holds can keep answering for days
+     * or longer (images are cached as unchanging for a year). `purging`: the edge cache is
+     * being cleared too.
+     */
+    cache: 'may_linger' | 'purging' | (string & {});
+    [k: string]: unknown;
+}
 /** 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>). */
@@ -2280,6 +2311,34 @@ declare class OwV2Client {
         key?: string;
         ticket?: OwMediaTicket;
     }): Promise<OwUploadedImage>;
+    /**
+     * POST /media/remove-ticket -- permission to remove ONE image (a write key and its
+     * PIN). The image's uploader may remove it, and so may the world's owner key; an
+     * agent seat answers as its sponsor. Only images uploaded with a ticket qualify.
+     * `key` is the object key, or the whole image_url (the part after the host is taken).
+     * The reply's `referenced` counts the world's elements still showing the image.
+     * Refusals: 403 `permission_error` (neither uploader nor owner), 404 `not_found`
+     * (no removable image under this key), 409 `removal_in_flight` (a ticket for this
+     * image is already out) and 409 `upload_pending` (an upload is not yet recorded), both
+     * with Retry-After.
+     */
+    createRemovalTicket(key: string): Promise<OwRemovalTicket>;
+    /**
+     * Remove one uploaded image: a removal ticket from the API, then the removal at the
+     * edge (the API key never leaves for the edge). Pass the object key or the whole
+     * image_url, or a ticket from createRemovalTicket() to use it instead of fetching one.
+     * The bytes go back to the uploading account's storage.
+     *
+     * Removal does not touch elements: clear or replace their `image_url` yourself (the
+     * ticket's `referenced` says how many there are). A copy already cached by the network
+     * or a browser can keep answering for a while (`cache: 'may_linger'`). The edge's
+     * refusals arrive as OwApiError with its code: 401 `ticket_expired` / `ticket_used` /
+     * `ticket_invalid`, 403 `not_removable`, 502 `remove_failed` (nothing removed; the
+     * ticket is still unspent).
+     */
+    removeImage(keyOrUrl: string, opts?: {
+        ticket?: OwRemovalTicket;
+    }): Promise<OwRemovedImage>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -2653,4 +2712,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, 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, 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 };

package/dist/index.js

@@ -348,6 +348,44 @@ var OwV2Client = class {
     if (!res.ok) throw await errorFromResponse(res);
     return await res.json();
   }
+  /**
+   * POST /media/remove-ticket -- permission to remove ONE image (a write key and its
+   * PIN). The image's uploader may remove it, and so may the world's owner key; an
+   * agent seat answers as its sponsor. Only images uploaded with a ticket qualify.
+   * `key` is the object key, or the whole image_url (the part after the host is taken).
+   * The reply's `referenced` counts the world's elements still showing the image.
+   * Refusals: 403 `permission_error` (neither uploader nor owner), 404 `not_found`
+   * (no removable image under this key), 409 `removal_in_flight` (a ticket for this
+   * image is already out) and 409 `upload_pending` (an upload is not yet recorded), both
+   * with Retry-After.
+   */
+  async createRemovalTicket(key) {
+    return this.request("POST", "/media/remove-ticket", { body: { key: objectKey(key) } });
+  }
+  /**
+   * Remove one uploaded image: a removal ticket from the API, then the removal at the
+   * edge (the API key never leaves for the edge). Pass the object key or the whole
+   * image_url, or a ticket from createRemovalTicket() to use it instead of fetching one.
+   * The bytes go back to the uploading account's storage.
+   *
+   * Removal does not touch elements: clear or replace their `image_url` yourself (the
+   * ticket's `referenced` says how many there are). A copy already cached by the network
+   * or a browser can keep answering for a while (`cache: 'may_linger'`). The edge's
+   * refusals arrive as OwApiError with its code: 401 `ticket_expired` / `ticket_used` /
+   * `ticket_invalid`, 403 `not_removable`, 502 `remove_failed` (nothing removed; the
+   * ticket is still unspent).
+   */
+  async removeImage(keyOrUrl, opts = {}) {
+    const ticket = opts.ticket ?? await this.createRemovalTicket(keyOrUrl);
+    let res;
+    try {
+      res = await this.fetchImpl(ticket.remove_url, { method: "POST", headers: { Authorization: `Bearer ${ticket.ticket}` } });
+    } catch (cause) {
+      throw new OwNetworkError(`OnlyWorlds image removal failed: POST ${ticket.remove_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
@@ -423,6 +461,10 @@ function mintUuid(now = Date.now()) {
   for (let i = 0; i < 256; i++) hex.push((i + 256).toString(16).slice(1));
   return hex[bytes[0]] + hex[bytes[1]] + hex[bytes[2]] + hex[bytes[3]] + "-" + hex[bytes[4]] + hex[bytes[5]] + "-" + hex[bytes[6]] + hex[bytes[7]] + "-" + hex[bytes[8]] + hex[bytes[9]] + "-" + hex[bytes[10]] + hex[bytes[11]] + hex[bytes[12]] + hex[bytes[13]] + hex[bytes[14]] + hex[bytes[15]];
 }
+function objectKey(keyOrUrl) {
+  if (!/^https?:\/\//i.test(keyOrUrl)) return keyOrUrl;
+  return decodeURIComponent(new URL(keyOrUrl).pathname.replace(/^\/+/, ""));
+}
 function buildQuery(params) {
   const q = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) {

package/package.json

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