@thatopen/services 0.9.0 → 0.10.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);
@@ -7161,6 +7162,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 +7218,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 +7586,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 +7640,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 +7666,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 +7720,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 +7846,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 +7912,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 +7984,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 +8067,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';
 
@@ -305,6 +306,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 +341,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 +669,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 +750,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 {};