@org-quicko/silo-client 1.0.1 → 1.1.1

package/dist/index.js

@@ -84,6 +84,9 @@ class ApiPath {
   static mediaAssetUsages(id) {
     return `${ApiPath.mediaAsset(id)}/usages`;
   }
+  static mediaAssetContent(id) {
+    return `${ApiPath.mediaAsset(id)}/content`;
+  }
   static mediaBulkDelete() {
     return "/api/media/delete";
   }
@@ -130,6 +133,22 @@ class MediaAssetMapper {
   }
 }
 
+// src/media/media-file.ts
+class MediaFile {
+  static toBlob(bytes, contentType) {
+    if (bytes instanceof Blob)
+      return bytes;
+    return new Blob([bytes], contentType ? { type: contentType } : undefined);
+  }
+  static nameOf(input, explicit) {
+    if (explicit)
+      return explicit;
+    if (input instanceof File && input.name)
+      return input.name;
+    throw new Error("media: a Blob has no filename — pass { filename } explicitly");
+  }
+}
+
 // src/media/media-reference.ts
 class MediaReference {
   static Scheme = "silo://media/";
@@ -189,12 +208,14 @@ var DefaultUsageLimit = 50;
 class MediaUsagePage extends Page {
   transport;
   assetId;
+  requestOptions;
   visible;
   visibleCapped;
-  constructor(rows, total, visible, visibleCapped, window, transport, assetId) {
+  constructor(rows, total, visible, visibleCapped, window, transport, assetId, requestOptions) {
     super(rows, total, window);
     this.transport = transport;
     this.assetId = assetId;
+    this.requestOptions = requestOptions;
     this.visible = visible;
     this.visibleCapped = visibleCapped;
   }
@@ -209,11 +230,11 @@ class MediaUsagePage extends Page {
   }
   async next(options) {
     const window = this.windowForNext();
-    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, options) : null;
+    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, { ...this.requestOptions, ...options }) : null;
   }
   async previous(options) {
     const window = this.window.previous();
-    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, options) : null;
+    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, { ...this.requestOptions, ...options }) : null;
   }
   static load(transport, assetId, query, options) {
     const window = new PageWindow(query.limit ?? DefaultUsageLimit, query.offset ?? 0);
@@ -225,10 +246,11 @@ class MediaUsagePage extends Page {
       path: ApiPath.mediaAssetUsages(assetId),
       query: { limit: window.limit, offset: window.offset },
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     const mapped = MediaAssetMapper.toUsagePage(body);
-    return new MediaUsagePage(mapped.items, mapped.total, mapped.visible, mapped.visibleCapped, window, transport, assetId);
+    return new MediaUsagePage(mapped.items, mapped.total, mapped.visible, mapped.visibleCapped, window, transport, assetId, options);
   }
 }
 
@@ -291,6 +313,22 @@ class MediaAsset {
   async setTags(tags, options) {
     return this.patch({ tags: [...tags] }, options);
   }
+  async replace(input, options) {
+    const form = new FormData;
+    if (input instanceof Blob) {
+      form.set("file", input, MediaFile.nameOf(input, options?.filename));
+    } else {
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
+    }
+    const payload = await this.transport.upload({
+      method: "POST",
+      path: ApiPath.mediaAssetContent(this.id),
+      signal: options?.signal,
+      timeoutMilliseconds: options?.timeoutMilliseconds
+    }, form);
+    this.record = MediaAssetMapper.toRecord(payload);
+    return this;
+  }
   async delete(options) {
     await this.transport.empty({
       method: "DELETE",
@@ -308,7 +346,8 @@ class MediaAsset {
       method: "GET",
       path: ApiPath.mediaAsset(this.id),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache ?? "refresh"
     });
     this.record = MediaAssetMapper.toRecord(payload);
     return this;
@@ -370,7 +409,8 @@ class MediaFolders {
       method: "GET",
       path: ApiPath.mediaFolders(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return body.items;
   }
@@ -412,21 +452,23 @@ class MediaFolders {
 class MediaPage extends Page {
   transport;
   wireQuery;
-  constructor(rows, total, window, transport, wireQuery) {
+  requestOptions;
+  constructor(rows, total, window, transport, wireQuery, requestOptions) {
     super(rows, total, window);
     this.transport = transport;
     this.wireQuery = wireQuery;
+    this.requestOptions = requestOptions;
   }
   get files() {
     return this.rows;
   }
   async next(options) {
     const window = this.windowForNext();
-    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, options) : null;
+    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, { ...this.requestOptions, ...options }) : null;
   }
   async previous(options) {
     const window = this.window.previous();
-    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, options) : null;
+    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, { ...this.requestOptions, ...options }) : null;
   }
   static async loadWindow(transport, wireQuery, window, options) {
     const body = await transport.json({
@@ -434,10 +476,11 @@ class MediaPage extends Page {
       path: ApiPath.media(),
       query: { ...wireQuery, limit: window.limit, offset: window.offset },
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     const rows = body.items.map((payload) => new MediaAsset(transport, MediaAssetMapper.toRecord(payload)));
-    return new MediaPage(rows, body.total, new PageWindow(body.limit, body.offset), transport, wireQuery);
+    return new MediaPage(rows, body.total, new PageWindow(body.limit, body.offset), transport, wireQuery, options);
   }
 }
 
@@ -524,11 +567,11 @@ class Media {
     let options;
     if (input instanceof Blob) {
       const fileOptions = second ?? {};
-      form.set("file", input, Media.filenameOf(input, fileOptions.filename));
+      form.set("file", input, MediaFile.nameOf(input, fileOptions.filename));
       folder = fileOptions.folder;
       options = third ?? fileOptions;
     } else {
-      form.set("file", Media.toBlob(input.bytes, input.contentType), input.filename);
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
       folder = input.folder;
       options = second;
     }
@@ -557,7 +600,8 @@ class Media {
       method: "GET",
       path: ApiPath.mediaAsset(id),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return new MediaAsset(this.transport, MediaAssetMapper.toRecord(payload));
   }
@@ -566,7 +610,8 @@ class Media {
       method: "GET",
       path: ApiPath.mediaExtensions(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return body.items;
   }
@@ -596,18 +641,6 @@ class Media {
       sort: query.sort
     };
   }
-  static toBlob(bytes, contentType) {
-    if (bytes instanceof Blob)
-      return bytes;
-    return new Blob([bytes], contentType ? { type: contentType } : undefined);
-  }
-  static filenameOf(input, explicit) {
-    if (explicit)
-      return explicit;
-    if (input instanceof File && input.name)
-      return input.name;
-    throw new Error("media upload: a Blob has no filename — pass { filename } explicitly");
-  }
 }
 
 // src/variables/variable.ts
@@ -1291,6 +1324,132 @@ class Projects {
   }
 }
 
+// src/transport/caching-transport.ts
+class CachingTransport {
+  #fetchTransport;
+  #cache;
+  constructor(fetchTransport, cache) {
+    this.#fetchTransport = fetchTransport;
+    this.#cache = cache;
+  }
+  async json(request) {
+    if (request.method !== "GET")
+      return this.write(() => this.#fetchTransport.json(request));
+    if (request.cache === "bypass")
+      return this.#fetchTransport.json(request);
+    if (request.signal?.aborted)
+      throw new RequestAbortedError(request.method, request.path);
+    let prepared;
+    try {
+      prepared = this.#fetchTransport.prepare(request);
+    } catch (caught) {
+      throw this.#fetchTransport.preparationFailure(request, caught);
+    }
+    const key = JSON.stringify([prepared.url, [...prepared.headers]]);
+    if (request.cache !== "refresh") {
+      const cached = this.#cache.get(key);
+      if (cached)
+        return cached.body;
+    }
+    const ticket = this.#cache.start(key);
+    try {
+      const body = await this.#fetchTransport.jsonPrepared(request, prepared);
+      this.#cache.set(key, ticket, body);
+      return body;
+    } finally {
+      this.#cache.finish(key, ticket);
+    }
+  }
+  empty(request) {
+    return request.method === "GET" ? this.#fetchTransport.empty(request) : this.write(() => this.#fetchTransport.empty(request));
+  }
+  stream(request) {
+    return request.method === "GET" ? this.#fetchTransport.stream(request) : this.write(() => this.#fetchTransport.stream(request));
+  }
+  upload(request, form) {
+    return request.method === "GET" ? this.#fetchTransport.upload(request, form) : this.write(() => this.#fetchTransport.upload(request, form));
+  }
+  async write(dispatch) {
+    this.#cache.clear();
+    try {
+      return await dispatch();
+    } finally {
+      this.#cache.clear();
+    }
+  }
+}
+
+// src/cache/response-cache.ts
+import { TTLCache } from "@isaacs/ttlcache";
+
+class ResponseCache {
+  #store;
+  #pending = new Map;
+  constructor(options) {
+    this.#store = new TTLCache({
+      ttl: options.ttlMilliseconds,
+      ...options.maxEntries === undefined || options.maxEntries === Infinity ? {} : { max: options.maxEntries },
+      checkAgeOnGet: true,
+      updateAgeOnGet: false
+    });
+  }
+  get size() {
+    return this.#store.size;
+  }
+  get(key) {
+    const cached = this.#store.get(key);
+    return cached === undefined ? undefined : { body: structuredClone(cached.body) };
+  }
+  set(key, ticket, body) {
+    if (this.#pending.get(key) !== ticket)
+      return;
+    this.#store.set(key, { body: structuredClone(body) });
+  }
+  start(key) {
+    const ticket = Symbol();
+    this.#pending.set(key, ticket);
+    return ticket;
+  }
+  finish(key, ticket) {
+    if (this.#pending.get(key) === ticket)
+      this.#pending.delete(key);
+  }
+  clear() {
+    this.#pending.clear();
+    this.#store.clear();
+  }
+}
+
+// src/cache/silo-cache.ts
+class SiloCache {
+  #responseCache;
+  constructor(options) {
+    if (options !== undefined)
+      SiloCache.validate(options);
+    this.#responseCache = options === undefined ? undefined : new ResponseCache(options);
+  }
+  get enabled() {
+    return this.#responseCache !== undefined;
+  }
+  get size() {
+    return this.#responseCache?.size ?? 0;
+  }
+  clear() {
+    this.#responseCache?.clear();
+  }
+  wrap(fetchTransport) {
+    return this.#responseCache ? new CachingTransport(fetchTransport, this.#responseCache) : fetchTransport;
+  }
+  static validate(options) {
+    if (!Number.isSafeInteger(options.ttlMilliseconds) || options.ttlMilliseconds <= 0) {
+      throw new TypeError("SiloOptions.cache.ttlMilliseconds must be a positive finite safe integer");
+    }
+    if (options.maxEntries !== undefined && options.maxEntries !== Infinity && (!Number.isSafeInteger(options.maxEntries) || options.maxEntries <= 0)) {
+      throw new TypeError("SiloOptions.cache.maxEntries must be a positive safe integer or Infinity");
+    }
+  }
+}
+
 // src/errors/silo-error.ts
 class SiloError extends Error {
   status;
@@ -1471,12 +1630,19 @@ class NetworkError extends Error {
   method;
   path;
   constructor(method, path, cause) {
-    super(`network error on ${method} ${path}: the request never reached the server`, { cause });
+    super(`network error on ${method} ${path}: the request never reached the server${NetworkError.reason(cause)}`, { cause });
     this.name = "NetworkError";
     this.method = method;
     this.path = path;
     Object.setPrototypeOf(this, NetworkError.prototype);
   }
+  static reason(cause) {
+    if (cause instanceof Error && cause.message)
+      return ` (${cause.message})`;
+    if (typeof cause === "string" && cause)
+      return ` (${cause})`;
+    return "";
+  }
 }
 
 // src/errors/timeout-error.ts
@@ -1578,60 +1744,80 @@ class ResponseDecoder {
   }
 }
 
-// src/transport/transport.ts
-class Transport {
-  url;
-  key;
-  headers;
-  timeoutMilliseconds;
-  fetchFunction;
+// src/transport/fetch-transport.ts
+class FetchTransport {
+  #url;
+  #key;
+  #headers;
+  #timeoutMilliseconds;
+  #fetchFunction;
   constructor(options) {
-    this.url = Transport.normalizeUrl(options.url);
-    this.key = options.key;
-    this.headers = options.headers ?? {};
-    this.timeoutMilliseconds = options.timeoutMilliseconds;
-    this.fetchFunction = options.fetch ?? fetch;
+    this.#url = FetchTransport.normalizeUrl(options.url);
+    this.#key = options.key;
+    this.#headers = options.headers ?? {};
+    this.#timeoutMilliseconds = options.timeoutMilliseconds;
+    this.#fetchFunction = FetchTransport.resolveFetch(options.fetch);
   }
   async json(request) {
     const response = await this.execute(request);
     return await ResponseDecoder.decode(response, request, true);
   }
+  async jsonPrepared(request, prepared) {
+    const response = await this.execute(request, prepared);
+    return await ResponseDecoder.decode(response, request, true);
+  }
   async empty(request) {
     const response = await this.execute(request);
     await ResponseDecoder.decode(response, request, false);
   }
   async stream(request) {
-    const response = await this.execute(request);
-    return response.body;
+    return (await this.execute(request)).body;
   }
   async upload(request, form) {
-    const response = await this.execute(request, form);
+    const response = await this.execute(request, undefined, form);
     return await ResponseDecoder.decode(response, request, true);
   }
   withKey(key) {
-    return new Transport({ ...this.snapshot(), key });
+    return new FetchTransport({ ...this.snapshot(), key });
   }
   withUrl(url) {
-    return new Transport({ ...this.snapshot(), url });
+    return new FetchTransport({ ...this.snapshot(), url });
+  }
+  prepare(request, form) {
+    const rawHeaders = { ...this.#headers, ...request.headers };
+    if (this.#key)
+      rawHeaders.Authorization = `Bearer ${this.#key}`;
+    if (!form && request.body !== undefined && !("Content-Type" in rawHeaders)) {
+      rawHeaders["Content-Type"] = "application/json";
+    }
+    return {
+      url: `${this.#url}${request.path}${QueryString.build(request.query)}`,
+      headers: new Headers(rawHeaders),
+      body: form ?? (request.body === undefined ? undefined : JSON.stringify(request.body))
+    };
+  }
+  preparationFailure(request, caught) {
+    return new NetworkError(request.method, request.path, caught);
   }
   snapshot() {
     return {
-      url: this.url,
-      key: this.key,
-      headers: this.headers,
-      timeoutMilliseconds: this.timeoutMilliseconds,
-      fetch: this.fetchFunction
+      url: this.#url,
+      key: this.#key,
+      headers: this.#headers,
+      timeoutMilliseconds: this.#timeoutMilliseconds,
+      fetch: this.#fetchFunction
     };
   }
-  async execute(request, form) {
-    const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.timeoutMilliseconds);
-    const url = `${this.url}${request.path}${QueryString.build(request.query)}`;
+  async execute(request, prepared, form) {
+    const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.#timeoutMilliseconds);
+    const sendRequest = this.#fetchFunction;
     let response;
     try {
-      response = await this.fetchFunction(url, {
+      const outbound = prepared ?? this.prepare(request, form);
+      response = await sendRequest(outbound.url, {
         method: request.method,
-        headers: this.buildHeaders(request, Boolean(form)),
-        body: form ?? (request.body === undefined ? undefined : JSON.stringify(request.body)),
+        headers: outbound.headers,
+        body: outbound.body,
         signal: abortSignals.signal
       });
     } catch (caught) {
@@ -1645,44 +1831,44 @@ class Transport {
     return response;
   }
   transportFailure(request, abortSignals, caught) {
-    const firedBy = abortSignals.firedBy();
-    if (firedBy === "timeout") {
-      return new TimeoutError(request.method, request.path, request.timeoutMilliseconds ?? this.timeoutMilliseconds ?? 0);
+    if (abortSignals.firedBy() === "timeout") {
+      return new TimeoutError(request.method, request.path, request.timeoutMilliseconds ?? this.#timeoutMilliseconds ?? 0);
     }
-    if (firedBy === "caller") {
+    if (abortSignals.firedBy() === "caller")
       return new RequestAbortedError(request.method, request.path);
-    }
     return new NetworkError(request.method, request.path, caught);
   }
-  buildHeaders(request, isUpload) {
-    const headers = { ...this.headers, ...request.headers };
-    if (this.key)
-      headers["Authorization"] = `Bearer ${this.key}`;
-    if (!isUpload && request.body !== undefined && !("Content-Type" in headers)) {
-      headers["Content-Type"] = "application/json";
-    }
-    return headers;
-  }
   static normalizeUrl(url) {
     return url.replace(/\/+$/, "");
   }
+  static resolveFetch(fetchFunction) {
+    if (fetchFunction)
+      return fetchFunction;
+    if (typeof globalThis.fetch !== "function") {
+      throw new Error("this runtime has no global fetch: pass one as SiloOptions.fetch");
+    }
+    return globalThis.fetch.bind(globalThis);
+  }
 }
 
 // src/silo.ts
 class Silo {
   projects;
   media;
+  cache;
   options;
   transport;
   constructor(options) {
-    this.options = options;
-    this.transport = new Transport({
+    this.cache = options.cache instanceof SiloCache ? options.cache : new SiloCache(options.cache);
+    this.options = { ...options, cache: this.cache };
+    const fetchTransport = new FetchTransport({
       url: options.url,
       key: options.key,
       headers: options.headers,
       timeoutMilliseconds: options.timeoutMilliseconds,
       fetch: options.fetch
     });
+    this.transport = this.cache.wrap(fetchTransport);
     this.projects = new Projects(this.transport);
     this.media = new Media(this.transport);
   }
@@ -1700,7 +1886,8 @@ class Silo {
       method: "GET",
       path: ApiPath.health(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: "bypass"
     });
   }
   withKey(key) {
@@ -1750,6 +1937,7 @@ class RouteInventory {
     "PATCH /api/media/:id",
     "DELETE /api/media/:id",
     "GET /api/media/:id/usages",
+    "POST /api/media/:id/content",
     "POST /api/media/delete",
     "GET /api/media/folders",
     "POST /api/media/folders",
@@ -1760,6 +1948,7 @@ class RouteInventory {
     "GET /api/session": "key introspection, an operator surface",
     "GET /api/keys": "keys and claims are an operator surface",
     "POST /api/keys": "keys and claims are an operator surface",
+    "PATCH /api/keys/:id": "keys and claims are an operator surface",
     "DELETE /api/keys/:id": "keys and claims are an operator surface",
     "GET /api/audit": "an operator surface",
     "GET /api/observability": "an operator surface",
@@ -1881,6 +2070,7 @@ export {
   SortTerm,
   Sort,
   SiloError,
+  SiloCache,
   Silo,
   SearchReach,
   SearchPage,

package/dist/media/media-asset.d.cts

@@ -1,6 +1,7 @@
 import type { RequestOptions } from "../request-options.cjs";
 import type { Transport } from "../transport/transport.cjs";
 import type { MediaDeleteOptions } from "./media-delete-options.cjs";
+import type { MediaReplace, MediaReplaceOptions } from "./media-replace.cjs";
 import type { MediaUsageQuery } from "./media-usage-page.cjs";
 import { MediaUsagePage } from "./media-usage-page.cjs";
 /** `MediaAsset`'s mapped state — `MediaAssetMapper.toRecord`'s output. */
@@ -53,6 +54,22 @@ export declare class MediaAsset {
     moveTo(folder: string, options?: RequestOptions): Promise<this>;
     /** REPLACES the tag list — `PATCH` replaces, it does not append. */
     setTags(tags: readonly string[], options?: RequestOptions): Promise<this>;
+    /**
+     * Swaps the bytes behind this asset (D67). `id`, `reference`, `url`,
+     * `filename` and `folder` all survive; `hash`, `sizeInBytes` and
+     * `contentType` are re-read from the server's answer.
+     *
+     * Every entry referencing it now resolves to the new file, without any of
+     * them being rewritten — which is the point, and the reason the server asks
+     * for `media:replace` **and** `entries:update` at every scope that refers
+     * to it.
+     *
+     * The new file must keep the current extension: the blob key's suffix is
+     * derived from the filename at upload and is the visible tail of the URL on
+     * a bucket-backed instance, so a `.png` asset takes a `.png` replacement.
+     * Converting a file is a new upload, not a replacement of this one.
+     */
+    replace(input: MediaReplace, options?: MediaReplaceOptions): Promise<this>;
     /** Refused while an entry references it; `{ force: true }` also needs
      * `entries:update` on every scope this asset reaches. */
     delete(options?: MediaDeleteOptions): Promise<void>;

package/dist/media/media-asset.d.ts

@@ -1,6 +1,7 @@
 import type { RequestOptions } from "../request-options.js";
 import type { Transport } from "../transport/transport.js";
 import type { MediaDeleteOptions } from "./media-delete-options.js";
+import type { MediaReplace, MediaReplaceOptions } from "./media-replace.js";
 import type { MediaUsageQuery } from "./media-usage-page.js";
 import { MediaUsagePage } from "./media-usage-page.js";
 /** `MediaAsset`'s mapped state — `MediaAssetMapper.toRecord`'s output. */
@@ -53,6 +54,22 @@ export declare class MediaAsset {
     moveTo(folder: string, options?: RequestOptions): Promise<this>;
     /** REPLACES the tag list — `PATCH` replaces, it does not append. */
     setTags(tags: readonly string[], options?: RequestOptions): Promise<this>;
+    /**
+     * Swaps the bytes behind this asset (D67). `id`, `reference`, `url`,
+     * `filename` and `folder` all survive; `hash`, `sizeInBytes` and
+     * `contentType` are re-read from the server's answer.
+     *
+     * Every entry referencing it now resolves to the new file, without any of
+     * them being rewritten — which is the point, and the reason the server asks
+     * for `media:replace` **and** `entries:update` at every scope that refers
+     * to it.
+     *
+     * The new file must keep the current extension: the blob key's suffix is
+     * derived from the filename at upload and is the visible tail of the URL on
+     * a bucket-backed instance, so a `.png` asset takes a `.png` replacement.
+     * Converting a file is a new upload, not a replacement of this one.
+     */
+    replace(input: MediaReplace, options?: MediaReplaceOptions): Promise<this>;
     /** Refused while an entry references it; `{ force: true }` also needs
      * `entries:update` on every scope this asset reaches. */
     delete(options?: MediaDeleteOptions): Promise<void>;

package/dist/media/media-file.d.cts

@@ -0,0 +1,16 @@
+/**
+ * Turning what a caller passed into the two things a multipart part needs: a
+ * `Blob` and a filename.
+ *
+ * Shared by `Media.upload` and `MediaAsset.replace` (D67) rather than copied
+ * into the second. The filename is not cosmetic on either path — the server
+ * reads the extension off it to decide what the library accepts, and on a
+ * replace to decide whether the file's type is changing at all — so the two
+ * entry points must derive it the same way.
+ */
+export declare class MediaFile {
+    static toBlob(bytes: Uint8Array | ArrayBuffer | Blob, contentType?: string): Blob;
+    /** A `File` carries its own name; a bare `Blob` does not, and sending it
+     * as "blob" is worse than refusing outright. */
+    static nameOf(input: Blob, explicit?: string): string;
+}

package/dist/media/media-file.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Turning what a caller passed into the two things a multipart part needs: a
+ * `Blob` and a filename.
+ *
+ * Shared by `Media.upload` and `MediaAsset.replace` (D67) rather than copied
+ * into the second. The filename is not cosmetic on either path — the server
+ * reads the extension off it to decide what the library accepts, and on a
+ * replace to decide whether the file's type is changing at all — so the two
+ * entry points must derive it the same way.
+ */
+export declare class MediaFile {
+    static toBlob(bytes: Uint8Array | ArrayBuffer | Blob, contentType?: string): Blob;
+    /** A `File` carries its own name; a bare `Blob` does not, and sending it
+     * as "blob" is worse than refusing outright. */
+    static nameOf(input: Blob, explicit?: string): string;
+}

package/dist/media/media-page.d.cts

@@ -9,6 +9,7 @@ import { MediaAsset } from "./media-asset.cjs";
 export declare class MediaPage extends Page<MediaAsset> {
     private readonly transport;
     private readonly wireQuery;
+    private readonly requestOptions;
     private constructor();
     get files(): readonly MediaAsset[];
     next(options?: RequestOptions): Promise<MediaPage | null>;

package/dist/media/media-page.d.ts

@@ -9,6 +9,7 @@ import { MediaAsset } from "./media-asset.js";
 export declare class MediaPage extends Page<MediaAsset> {
     private readonly transport;
     private readonly wireQuery;
+    private readonly requestOptions;
     private constructor();
     get files(): readonly MediaAsset[];
     next(options?: RequestOptions): Promise<MediaPage | null>;