@onlyworlds/sdk 4.7.3 → 4.8.1

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.31.00";
+declare const ONLYWORLDS_VERSION: "00.32.00";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -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)) {
@@ -433,7 +475,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
-var ONLYWORLDS_VERSION = "00.31.00";
+var ONLYWORLDS_VERSION = "00.32.00";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@onlyworlds/sdk",
-  "version": "4.7.3",
-  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "types": "dist/index.d.ts",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "AGENTS.md",
-    "CHANGELOG.md",
-    "SCHEMA.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "pretest": "npm run build",
-    "test": "node --test",
-    "codegen": "python codegen/generate_types.py",
-    "codegen:check": "python codegen/generate_types.py --check",
-    "schema:verify": "python codegen/verify_dist.py",
-    "schema:check": "npm run schema:verify && npm run codegen:check",
-    "prepublishOnly": "npm run build",
-    "release:verify": "node codegen/verify_release.mjs"
-  },
-  "keywords": [
-    "onlyworlds",
-    "worldbuilding",
-    "api",
-    "sdk",
-    "typescript",
-    "rpg",
-    "ttrpg",
-    "game-development"
-  ],
-  "author": "OnlyWorlds",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OnlyWorlds/sdk.git"
-  },
-  "homepage": "https://onlyworlds.github.io/",
-  "bugs": {
-    "url": "https://github.com/OnlyWorlds/sdk/issues"
-  },
-  "devDependencies": {
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.5.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@onlyworlds/sdk",
+  "version": "4.8.1",
+  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "SCHEMA.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "codegen": "python codegen/generate_types.py",
+    "codegen:check": "python codegen/generate_types.py --check",
+    "schema:verify": "python codegen/verify_dist.py",
+    "schema:check": "npm run schema:verify && npm run codegen:check",
+    "prepublishOnly": "npm run build",
+    "release:verify": "node codegen/verify_release.mjs"
+  },
+  "keywords": [
+    "onlyworlds",
+    "worldbuilding",
+    "api",
+    "sdk",
+    "typescript",
+    "rpg",
+    "ttrpg",
+    "game-development"
+  ],
+  "author": "OnlyWorlds",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OnlyWorlds/sdk.git"
+  },
+  "homepage": "https://onlyworlds.github.io/",
+  "bugs": {
+    "url": "https://github.com/OnlyWorlds/sdk/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}