@thatopen/services 0.9.1 → 0.11.0

package/dist/cli.js

@@ -6795,6 +6795,7 @@ Object.assign(lookup, {
   io: lookup,
   connect: lookup
 });
+const STORAGE_BATCH_MAX = 100;
 function parseErrorBody(body) {
   try {
     const json = JSON.parse(body);
@@ -6810,12 +6811,22 @@ function parseErrorBody(body) {
   }
   return {};
 }
+function retryAfterFromDetails(details) {
+  if (!details || typeof details !== "object") return void 0;
+  const value2 = details.retryAfter;
+  return typeof value2 === "number" && Number.isFinite(value2) && value2 >= 0 ? value2 : void 0;
+}
 class RequestError extends Error {
   status;
   code;
   details;
   body;
-  constructor(status, statusText, body) {
+  /**
+   * Seconds to wait before retrying, taken from the `Retry-After` header or
+   * from `details.retryAfter`. Only present on rate-limited (429) responses.
+   */
+  retryAfter;
+  constructor(status, statusText, body, retryAfter) {
     const parsed = parseErrorBody(body);
     super(parsed.message ?? `${statusText || "Request failed"} (${status})`);
     this.name = "RequestError";
@@ -6823,6 +6834,7 @@ class RequestError extends Error {
     this.code = parsed.code;
     this.details = parsed.details;
     this.body = body;
+    this.retryAfter = retryAfter ?? retryAfterFromDetails(parsed.details);
   }
 }
 const FOLDER_PATH = "item/folder";
@@ -6833,6 +6845,35 @@ const HIDDEN_PATH = "hidden";
 const ITEM_TYPE_FILE = "FILE";
 const ITEM_TYPE_COMPONENT = "TOOL";
 const ITEM_TYPE_APP = "APP";
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 3e4;
+const RETRY_JITTER_RATIO = 0.25;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function parseRetryAfter(response) {
+  const raw = response.headers?.get?.("Retry-After");
+  if (!raw) return void 0;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds);
+  const timestamp = Date.parse(raw);
+  if (Number.isNaN(timestamp)) return void 0;
+  return Math.max(0, (timestamp - Date.now()) / 1e3);
+}
+function isRetryable(error2) {
+  if (!(error2 instanceof RequestError)) return true;
+  return error2.status === 429 || error2.status >= 500;
+}
+function retryDelayMs(error2, attempt) {
+  const backoff = Math.min(
+    RETRY_BASE_DELAY_MS * 2 ** attempt,
+    RETRY_MAX_DELAY_MS
+  );
+  const jitter = backoff * RETRY_JITTER_RATIO * Math.random();
+  const serverDelay = error2 instanceof RequestError && error2.retryAfter != null ? error2.retryAfter * 1e3 : void 0;
+  if (serverDelay != null) {
+    return Math.min(serverDelay, RETRY_MAX_DELAY_MS) + jitter;
+  }
+  return backoff + jitter;
+}
 class EngineServicesClient {
   apiUrl;
   accessToken;
@@ -6905,7 +6946,9 @@ class EngineServicesClient {
     }
   }
   /**
-   * Sets the number of automatic retries for failed requests.
+   * Sets the number of automatic retries for failed requests. Retries use
+   * exponential backoff with jitter and honour `Retry-After`; only network
+   * failures, 429s and 5xx are retried.
    * @param retries - Number of retries (0 = no retries).
    */
   setRetries(retries) {
@@ -6965,7 +7008,7 @@ class EngineServicesClient {
     return this.accessToken;
   }
   async #requestApi(method, path2, requestData) {
-    const { body, query, contentType, retries, responseType } = requestData || {};
+    const { body, query, contentType, retries, responseType, retryAttempt } = requestData || {};
     const url2 = this.#buildUrl(path2);
     const cleanQuery = this.#cleanData(query);
     const token = await this.resolveAccessToken();
@@ -6991,7 +7034,8 @@ class EngineServicesClient {
         throw new RequestError(
           response.status,
           response.statusText,
-          textResponse
+          textResponse,
+          parseRetryAfter(response)
         );
       }
       if (responseType === "blob") {
@@ -6999,16 +7043,17 @@ class EngineServicesClient {
       }
       return response.json().then((data) => data).catch(() => void 0);
     } catch (e) {
-      let retriesAmmount = retries != null ? retries : this.retries;
-      if (retriesAmmount) {
-        retriesAmmount = retriesAmmount - 1;
+      const retriesLeft = retries != null ? retries : this.retries;
+      if (retriesLeft > 0 && isRetryable(e)) {
+        const attempt = retryAttempt ?? 0;
+        await sleep(retryDelayMs(e, attempt));
         return await this.#requestApi(method, path2, {
           ...requestData,
-          retries: retriesAmmount
+          retries: retriesLeft - 1,
+          retryAttempt: attempt + 1
         });
-      } else {
-        throw e;
       }
+      throw e;
     }
   }
   /**
@@ -7161,6 +7206,36 @@ class EngineServicesClient {
       `${ITEM_PATH}/${encodeURIComponent(fileId)}/version/${encodeURIComponent(versionTag)}/metadata`
     );
   }
+  /**
+   * Batch variant of {@link getFileVersionMetadata}. Reads the metadata of
+   * many (file, version) pairs in one request instead of one request per pair,
+   * which is what a file list needs when it hydrates a whole page at once.
+   *
+   * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+   * requests automatically. Entries come back in the order they were asked
+   * for; a pair the caller cannot read carries an `error` instead of
+   * `metadata`, so one bad id does not lose the whole page.
+   *
+   * @param entries - The `{ itemId, versionTag }` pairs to read.
+   * @param params - Optional flags such as `withDraft`.
+   */
+  async getFileVersionMetadataBatch(entries, params) {
+    const { withDraft } = params || {};
+    return await this.#requestBatches(
+      entries,
+      async (chunk) => (await this.#requestApi(
+        "POST",
+        `${ITEM_PATH}/batch/version-metadata`,
+        {
+          body: JSON.stringify({
+            entries: chunk,
+            ...withDraft !== void 0 && { withDraft }
+          }),
+          contentType: "application/json"
+        }
+      )).results
+    );
+  }
   // ─── Folders ─────────────────────────────────────────────────────
   /**
    * Lists all folders accessible by the current token.
@@ -7187,6 +7262,32 @@ class EngineServicesClient {
       `${FOLDER_PATH}/${folderId}`
     );
   }
+  /**
+   * Batch variant of {@link getFolder}. Resolves a known set of folder ids in
+   * one request — for example the parents behind a file list's breadcrumbs.
+   *
+   * Reach for {@link listFolders} instead when the whole (project) tree is
+   * wanted; this is for the case where the ids are already known.
+   *
+   * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+   * requests automatically. A folder the caller cannot read carries an
+   * `error` instead of `folder`.
+   *
+   * @param folderIds - The folder ids to resolve.
+   */
+  async getFoldersBatch(folderIds) {
+    return await this.#requestBatches(
+      folderIds,
+      async (chunk) => (await this.#requestApi(
+        "POST",
+        `${ITEM_PATH}/batch/folders`,
+        {
+          body: JSON.stringify({ folderIds: chunk }),
+          contentType: "application/json"
+        }
+      )).results
+    );
+  }
   /**
    * Creates a new folder.
    * @param name - Display name for the folder.
@@ -7529,15 +7630,12 @@ return main;`);
    */
   async downloadAppBundle(appId, params) {
     const { versionTag, withDraft } = params || {};
-    return await this.#requestFile(
-      `${ITEM_PATH}/${appId}/download/bundle`,
-      {
-        query: {
-          ...versionTag && { versionTag },
-          ...withDraft && { withDraft }
-        }
+    return await this.#requestFile(`${ITEM_PATH}/${appId}/download/bundle`, {
+      query: {
+        ...versionTag && { versionTag },
+        ...withDraft && { withDraft }
       }
-    );
+    });
   }
   /**
    * Archives (soft-deletes) an app.
@@ -7586,7 +7684,9 @@ return main;`);
       });
       if (!response.ok) {
         const text = await response.text().catch(() => "");
-        throw new Error(`Local server request failed: ${response.status} - ${text}`);
+        throw new Error(
+          `Local server request failed: ${response.status} - ${text}`
+        );
       }
       return await response.json();
     }
@@ -7610,7 +7710,9 @@ return main;`);
       const response = await fetch(url2, { method: "POST" });
       if (!response.ok) {
         const text = await response.text().catch(() => "");
-        throw new Error(`Local server request failed: ${response.status} - ${text}`);
+        throw new Error(
+          `Local server request failed: ${response.status} - ${text}`
+        );
       }
       return await response.json();
     }
@@ -7662,7 +7764,9 @@ return main;`);
       const response = await fetch(url2);
       if (!response.ok) {
         const text = await response.text().catch(() => "");
-        throw new Error(`Local server request failed: ${response.status} - ${text}`);
+        throw new Error(
+          `Local server request failed: ${response.status} - ${text}`
+        );
       }
       return await response.json();
     }
@@ -7786,6 +7890,40 @@ return main;`);
       { ...expiresIn != null && { query: { expiresIn } } }
     );
   }
+  /**
+   * Batch variant of {@link getHiddenFileSignedUrl}. Mints presigned URLs for
+   * many hidden files in one request.
+   *
+   * This is the right call for tile-based viewers (splats, point clouds),
+   * which mint a URL per piece as the camera moves. One request here replaces
+   * up to {@link STORAGE_BATCH_MAX} single calls, which keeps a busy session
+   * well under the per-endpoint rate limit.
+   *
+   * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+   * requests automatically. Entries come back in request order; a file that
+   * is gone or not accessible carries an `error` instead of a `url`, so the
+   * remaining tiles still load. Re-call to re-mint as `expiresAt` approaches.
+   *
+   * @param hiddenIds - The hidden files to sign.
+   * @param expiresIn - Desired URL lifetime in seconds (60–3600). Defaults to
+   *   900 (15 min) server-side; values are clamped to that range.
+   */
+  async getHiddenFileSignedUrlsBatch(hiddenIds, expiresIn) {
+    return await this.#requestBatches(
+      hiddenIds,
+      async (chunk) => (await this.#requestApi(
+        "POST",
+        `${ITEM_PATH}/${HIDDEN_PATH}/signed-url/batch`,
+        {
+          body: JSON.stringify({
+            hiddenFileIds: chunk,
+            ...expiresIn != null && { expiresIn }
+          }),
+          contentType: "application/json"
+        }
+      )).results
+    );
+  }
   /**
    * Lists all hidden files attached to a parent item.
    * @param parentFileId - The parent item's unique identifier.
@@ -7818,11 +7956,9 @@ return main;`);
   async uploadItemIcon(itemId, icon) {
     const formData = new FormData();
     formData.append("icon", icon);
-    return await this.#requestApi(
-      "PUT",
-      `${ITEM_PATH}/${itemId}/icon`,
-      { body: formData }
-    );
+    return await this.#requestApi("PUT", `${ITEM_PATH}/${itemId}/icon`, {
+      body: formData
+    });
   }
   /**
    * Downloads the icon for an item as a binary stream.
@@ -7892,6 +8028,38 @@ return main;`);
       { query: params }
     );
   }
+  /**
+   * Batch variant of {@link listVersions}. Lists the versions of many items in
+   * one request, which is what a file panel needs to render a whole page.
+   *
+   * The returned versions are the full records, metadata included, so a list
+   * that only needs version metadata does not need
+   * {@link getFileVersionMetadataBatch} on top.
+   *
+   * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+   * requests automatically. An item the caller cannot read carries an `error`
+   * instead of `versions`.
+   *
+   * @param itemIds - The items whose versions to list.
+   * @param params - Optional `{ archived }` filter, applied to every item.
+   */
+  async listVersionsBatch(itemIds, params = {}) {
+    const { archived } = params;
+    return await this.#requestBatches(
+      itemIds,
+      async (chunk) => (await this.#requestApi(
+        "POST",
+        `${ITEM_PATH}/batch/versions`,
+        {
+          body: JSON.stringify({
+            itemIds: chunk,
+            ...archived !== void 0 && { archived }
+          }),
+          contentType: "application/json"
+        }
+      )).results
+    );
+  }
   /**
    * Archives a version of an item. Archived versions remain available via
    * `listVersions({ archived: true })` and can be recovered or permanently
@@ -7943,6 +8111,21 @@ return main;`);
   // checkPermission, checkPermissionBatch) live on `PlatformClient` — they
   // cannot be called with an access token.
   // ─── Private Helpers ─────────────────────────────────────────────
+  /**
+   * Splits `inputs` into chunks the API accepts and concatenates the results,
+   * so callers never have to think about the batch ceiling. Chunks go out
+   * together; an empty input skips the network entirely, since the API
+   * rejects an empty batch.
+   */
+  async #requestBatches(inputs, requestChunk) {
+    if (!inputs.length) return [];
+    const chunks = [];
+    for (let start = 0; start < inputs.length; start += STORAGE_BATCH_MAX) {
+      chunks.push(inputs.slice(start, start + STORAGE_BATCH_MAX));
+    }
+    const responses = await Promise.all(chunks.map(requestChunk));
+    return responses.flat();
+  }
   async #downloadItem(itemId, params) {
     const { versionTag, withDraft } = params || {};
     return await this.#requestFile(`${ITEM_PATH}/${itemId}/download`, {

package/dist/core/client.d.ts

@@ -2,6 +2,7 @@ import { ExecutionEntity, ExecutionSuscriptionReturnType } from '../types/execut
 import { AppVersionProps, ComponentVersionProps, ComponentItem, AppItem, Item, ItemFolder, ItemVersion, ItemWithVersions } from '../types/items';
 import { CreateItemResponse, UpdateItemResponse } from '../types/response';
 import { CreateHiddenItemResult, CreateHiddenItemsBatchResult, HiddenFileEntity, Metadata } from '../types/files';
+import { HiddenFileSignedUrlBatchEntry, ItemFoldersBatchEntry, ItemVersionsBatchEntry, VersionMetadataBatchEntry, VersionMetadataBatchRequest } from '../types/batch';
 import { ThatOpenContext } from '../types/context';
 import { NpmCredentials } from '../types/npm';
 
@@ -83,7 +84,13 @@ export type DownloadItemFileParams = {
 };
 /** Configuration options for the {@link EngineServicesClient} constructor. */
 export type EngineServicesClientProps = {
-    /** Number of automatic retries on request failure. Default: 0. */
+    /**
+     * Number of automatic retries on request failure. Default: 0.
+     *
+     * Retries are spaced with exponential backoff plus jitter, and honour the
+     * server's `Retry-After` when it sends one. Only network failures, 429s and
+     * 5xx are retried — other 4xx fail immediately.
+     */
     retries?: number;
     /**
      * If true, sends the token as an `Authorization: Bearer` header instead of
@@ -166,7 +173,9 @@ export declare class EngineServicesClient {
      */
     constructor(accessToken: string, apiUrl: string, props?: EngineServicesClientProps);
     /**
-     * Sets the number of automatic retries for failed requests.
+     * Sets the number of automatic retries for failed requests. Retries use
+     * exponential backoff with jitter and honour `Retry-After`; only network
+     * failures, 429s and 5xx are retried.
      * @param retries - Number of retries (0 = no retries).
      */
     setRetries(retries: number): void;
@@ -305,6 +314,22 @@ export declare class EngineServicesClient {
     deleteFileVersionMetadata(fileId: string, versionTag: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Batch variant of {@link getFileVersionMetadata}. Reads the metadata of
+     * many (file, version) pairs in one request instead of one request per pair,
+     * which is what a file list needs when it hydrates a whole page at once.
+     *
+     * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+     * requests automatically. Entries come back in the order they were asked
+     * for; a pair the caller cannot read carries an `error` instead of
+     * `metadata`, so one bad id does not lose the whole page.
+     *
+     * @param entries - The `{ itemId, versionTag }` pairs to read.
+     * @param params - Optional flags such as `withDraft`.
+     */
+    getFileVersionMetadataBatch(entries: VersionMetadataBatchRequest[], params?: {
+        withDraft?: boolean;
+    }): Promise<VersionMetadataBatchEntry[]>;
     /**
      * Lists all folders accessible by the current token.
      * @param params - Optional filters for parent folder and archive status.
@@ -324,6 +349,20 @@ export declare class EngineServicesClient {
      * @param folderId - The folder's unique identifier.
      */
     getFolder(folderId: string): Promise<ItemFolder>;
+    /**
+     * Batch variant of {@link getFolder}. Resolves a known set of folder ids in
+     * one request — for example the parents behind a file list's breadcrumbs.
+     *
+     * Reach for {@link listFolders} instead when the whole (project) tree is
+     * wanted; this is for the case where the ids are already known.
+     *
+     * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+     * requests automatically. A folder the caller cannot read carries an
+     * `error` instead of `folder`.
+     *
+     * @param folderIds - The folder ids to resolve.
+     */
+    getFoldersBatch(folderIds: string[]): Promise<ItemFoldersBatchEntry[]>;
     /**
      * Creates a new folder.
      * @param name - Display name for the folder.
@@ -638,6 +677,25 @@ export declare class EngineServicesClient {
         url: string;
         expiresAt: string;
     }>;
+    /**
+     * Batch variant of {@link getHiddenFileSignedUrl}. Mints presigned URLs for
+     * many hidden files in one request.
+     *
+     * This is the right call for tile-based viewers (splats, point clouds),
+     * which mint a URL per piece as the camera moves. One request here replaces
+     * up to {@link STORAGE_BATCH_MAX} single calls, which keeps a busy session
+     * well under the per-endpoint rate limit.
+     *
+     * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+     * requests automatically. Entries come back in request order; a file that
+     * is gone or not accessible carries an `error` instead of a `url`, so the
+     * remaining tiles still load. Re-call to re-mint as `expiresAt` approaches.
+     *
+     * @param hiddenIds - The hidden files to sign.
+     * @param expiresIn - Desired URL lifetime in seconds (60–3600). Defaults to
+     *   900 (15 min) server-side; values are clamped to that range.
+     */
+    getHiddenFileSignedUrlsBatch(hiddenIds: string[], expiresIn?: number): Promise<HiddenFileSignedUrlBatchEntry[]>;
     /**
      * Lists all hidden files attached to a parent item.
      * @param parentFileId - The parent item's unique identifier.
@@ -700,6 +758,24 @@ export declare class EngineServicesClient {
     listVersions(itemId: string, params?: {
         archived?: boolean;
     }): Promise<ItemVersion[]>;
+    /**
+     * Batch variant of {@link listVersions}. Lists the versions of many items in
+     * one request, which is what a file panel needs to render a whole page.
+     *
+     * The returned versions are the full records, metadata included, so a list
+     * that only needs version metadata does not need
+     * {@link getFileVersionMetadataBatch} on top.
+     *
+     * Inputs longer than {@link STORAGE_BATCH_MAX} are split into several
+     * requests automatically. An item the caller cannot read carries an `error`
+     * instead of `versions`.
+     *
+     * @param itemIds - The items whose versions to list.
+     * @param params - Optional `{ archived }` filter, applied to every item.
+     */
+    listVersionsBatch(itemIds: string[], params?: {
+        archived?: boolean;
+    }): Promise<ItemVersionsBatchEntry[]>;
     /**
      * Archives a version of an item. Archived versions remain available via
      * `listVersions({ archived: true })` and can be recovered or permanently

package/dist/core/examples/batch-reads.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/request-error.d.ts

@@ -15,11 +15,27 @@
  *   }
  * }
  * ```
+ *
+ * @example Rate limiting
+ * ```ts
+ * catch (err) {
+ *   if (err instanceof RequestError && err.status === 429) {
+ *     console.log(err.code);       // "RATE_LIMITED"
+ *     console.log(err.details);    // { limit, windowSeconds, retryAfter, scope }
+ *     console.log(err.retryAfter); // seconds to wait before trying again
+ *   }
+ * }
+ * ```
  */
 export declare class RequestError extends Error {
     readonly status: number;
     readonly code?: string;
     readonly details?: unknown;
     readonly body: string;
-    constructor(status: number, statusText: string, body: string);
+    /**
+     * Seconds to wait before retrying, taken from the `Retry-After` header or
+     * from `details.retryAfter`. Only present on rate-limited (429) responses.
+     */
+    readonly retryAfter?: number;
+    constructor(status: number, statusText: string, body: string, retryAfter?: number);
 }