From ab2201b153ad1e1a936bb6c372831cf761d6a294 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antonio=20Gonz=C3=A1lez=20Viegas?=
 <antoniogviegas@hotmail.com>
Date: Sat, 27 Jun 2026 17:20:59 +0200
Subject: [PATCH] feat(client): add getHiddenFileSignedUrl for ranged streaming

Adds EngineServicesClient.getHiddenFileSignedUrl(hiddenId, expiresIn?), which
returns a short-lived signed URL ({ url, expiresAt }) for a hidden file. This
lets the browser fetch large hidden files directly with native HTTP Range
requests (e.g. streaming a point cloud's octree.bin) instead of downloading
the whole object. Re-call to refresh the URL when it nears expiry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/core/client.ts | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/core/client.ts b/src/core/client.ts
index a08883f..a7dca4a 100644
--- a/src/core/client.ts
+++ b/src/core/client.ts
@@ -1257,6 +1257,31 @@ export class EngineServicesClient {
     );
   }
 
+  /**
+   * Mints a short-lived presigned URL for a hidden file so the browser can
+   * stream it directly from storage with native HTTP `Range` requests (e.g. a
+   * point-cloud `octree.bin`), instead of proxying the whole object through the
+   * API. Re-call to re-mint when the URL nears/passes `expiresAt`; coalesce
+   * concurrent re-mints into a single in-flight call.
+   *
+   * The storage bucket's CORS must allow the `Range` request header and expose
+   * `Content-Range`, `Accept-Ranges` and `Content-Length` for the ranged fetch
+   * to succeed cross-origin.
+   *
+   * @param hiddenId - The hidden file's unique identifier.
+   * @param expiresIn - Desired URL lifetime in seconds (60–3600). Defaults to
+   *   900 (15 min) server-side; values are clamped to that range.
+   * @returns `{ url, expiresAt }` — `url` is the presigned GET URL, `expiresAt`
+   *   an ISO timestamp when it stops working.
+   */
+  async getHiddenFileSignedUrl(hiddenId: string, expiresIn?: number) {
+    return await this.#requestApi<{ url: string; expiresAt: string }>(
+      'GET',
+      `${ITEM_PATH}/${HIDDEN_PATH}/${hiddenId}/signed-url`,
+      { ...(expiresIn != null && { query: { expiresIn } }) },
+    );
+  }
+
   /**
    * Lists all hidden files attached to a parent item.
    * @param parentFileId - The parent item's unique identifier.