@telecrypt-io/storage 0.5.28 → 0.5.29

package/dist/core/operations.js

@@ -10,12 +10,12 @@
  * config (persistent crypto store, session credentials, etc.) is
  * platform-specific and stays with the caller.
  */
-import { withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
+import { readFileEventMetadata, withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
 import { EventType, MatrixError, RoomCreateTypeField, RoomType, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
 import { Method } from "matrix-js-sdk/lib/http-api/method.js";
-import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./errors.js";
-import { waitForCondition } from "./poll.js";
+import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
+import { ConditionTimeoutError, waitForCondition } from "./poll.js";
 import { validateMatrixEventId } from "./constants.js";
 import { validateName } from "./validation.js";
 import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
@@ -27,14 +27,12 @@ import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markT
  * server-advised backoff. Mirrors the harness library suite's
  * `withRateLimitRetry`; must not mask non-rate-limit failures.
  */
-const RATE_LIMIT_RETRIES = 6;
 const RATE_LIMIT_DEFAULT_DELAY_MS = 15_000;
-const RATE_LIMIT_MAX_DELAY_MS = 30_000;
-const RATE_LIMIT_MAX_TOTAL_DELAY_MS = 90_000;
+// JavaScript timers cannot represent a longer delay reliably. The operation's
+// own deadline remains the authority that stops retrying.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const MAX_DELETION_ROOMS = 4096;
 const MAX_DELETION_DEPTH = 128;
-const MAX_FILE_VERSION_CHAIN = 128;
-const MAX_LIST_ITEMS = 10000;
 const DEFAULT_MUTATION_TIMEOUT_MS = 5 * 60_000;
 const MAX_MUTATION_TIMEOUT_MS = 15 * 60_000;
 function createOperationDeadline(options) {
@@ -79,24 +77,17 @@ async function raceOperationDeadline(deadline, pending, kind) {
     finally {
         if (onAbort)
             deadline.signal.removeEventListener("abort", onAbort);
-        void pending.catch(() => undefined);
     }
 }
 async function withOperationDeadline(options, operation, kind = "read") {
     const deadline = createOperationDeadline(options);
-    let pending;
     try {
         ensureOperationActive(deadline.signal);
-        pending = Promise.resolve().then(() => operation(deadline.signal));
+        const pending = Promise.resolve().then(() => operation(deadline.signal));
         return await raceOperationDeadline(deadline, pending, kind);
     }
     finally {
         deadline.close();
-        // A caller-facing deadline must not wait for a broken provider, but the
-        // late result remains observed so an ignored AbortSignal cannot create an
-        // unhandled rejection.
-        if (pending)
-            void pending.catch(() => undefined);
     }
 }
 function isRateLimited(error) {
@@ -107,16 +98,28 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
+function requiresMutationReconciliation(error) {
+    return (error instanceof MutationOutcomeUnknownError ||
+        error instanceof RoomCreationAmbiguousError ||
+        error instanceof RoomCleanupIncompleteError ||
+        (error instanceof Error &&
+            error.cleanupIncomplete === true));
+}
 async function withRateLimitRetry(operation, signal) {
-    let totalDelay = 0;
-    for (let attempt = 0;; attempt++) {
+    for (;;) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         try {
             return await operation();
         }
         catch (error) {
-            if (!isRateLimited(error) || attempt >= RATE_LIMIT_RETRIES)
+            // A mutation that may have committed, or whose compensating cleanup is
+            // incomplete, must be reconciled by its owner before any retry. A
+            // server rate-limit response does not make repeating room creation safe.
+            if (requiresMutationReconciliation(error)) {
+                throw error;
+            }
+            if (!isRateLimited(error))
                 throw error;
             // The server's retry_after_ms only covers one token; tree operations
             // need several (kick + leave + forget). Wait at least 15s so the
@@ -131,12 +134,7 @@ async function withRateLimitRetry(operation, signal) {
                     }
                 }
             }
-            retryAfter = Math.min(retryAfter, RATE_LIMIT_MAX_DELAY_MS);
-            const remaining = RATE_LIMIT_MAX_TOTAL_DELAY_MS - totalDelay;
-            if (remaining <= 0)
-                throw error;
-            retryAfter = Math.min(retryAfter, remaining);
-            totalDelay += retryAfter;
+            retryAfter = Math.min(retryAfter, MAX_TIMER_DELAY_MS);
             await new Promise((resolve, reject) => {
                 let timer;
                 const onAbort = () => {
@@ -169,10 +167,12 @@ async function resolveTree(storage, treeId, signal) {
             signal,
         });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("storage space not found");
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("storage space not found");
+        throw new StorageError("storage space lookup failed", { cause: error });
     }
 }
 function isMarkedTreeDeleted(storage, treeId) {
@@ -197,10 +197,12 @@ async function resolveFile(storage, tree, fileId, signal) {
     try {
         return await waitForCondition(() => (isMarkedFileDeleted(storage, tree.id, fileId) ? null : tree.getFile(fileId)), { timeoutMs: 15000, signal });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("file not found");
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("file not found");
+        throw new StorageError("file lookup failed", { cause: error });
     }
 }
 function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large") {
@@ -223,8 +225,8 @@ function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large")
         try {
             children = tree.getDirectories();
         }
-        catch {
-            throw new StorageError("could not enumerate storage space descendants safely");
+        catch (error) {
+            throw new StorageError("could not enumerate storage space descendants safely", { cause: error });
         }
         if (children.length > MAX_DELETION_ROOMS) {
             throw new StorageError(tooLargeMessage);
@@ -250,8 +252,8 @@ function assertTreeEmptyForDeletion(storage, tree, spaces) {
             .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id) &&
             !isConfirmedDeletedFile(storage.getClient(), tree.id, file));
     }
-    catch {
-        throw new StorageError("could not enumerate storage files safely");
+    catch (error) {
+        throw new StorageError("could not enumerate storage files safely", { cause: error });
     }
     if (files.length > 0)
         throw new NonEmptyTreeError(tree.id);
@@ -360,8 +362,8 @@ function validateDeletionGraph(client, root, ids, deletedRooms) {
         try {
             directories = tree.getDirectories();
         }
-        catch {
-            throw new StorageError("delete graph is unsafe");
+        catch (error) {
+            throw new StorageError("delete graph is unsafe", { cause: error });
         }
         for (const child of directories)
             addEdge(id, child.id);
@@ -455,8 +457,10 @@ async function unlinkExternalParents(storage, rootId, externalParents, signal) {
         try {
             await relinkExternalParents(storage, rootId, externalParents, new AbortController().signal);
         }
-        catch {
-            throw new StorageError("delete graph unlink cleanup is incomplete");
+        catch (cleanupError) {
+            throw new StorageError("delete graph unlink cleanup is incomplete", {
+                cause: new AggregateError([error, cleanupError], "delete graph unlink and relink both failed", { cause: error }),
+            });
         }
         throw error;
     }
@@ -554,7 +558,7 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
         if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
             throw error;
         if (completedRoomIds.length > 0) {
-            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped");
+            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped", { cause: error });
         }
         throw error;
     }
@@ -565,14 +569,7 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
  * may otherwise leave a stale invite visible until the next sync.
  */
 function removeRoomFromLocalStore(client, roomId) {
-    try {
-        client.store?.removeRoom(roomId);
-    }
-    catch {
-        // Server-side leave/forget already completed; a store implementation that
-        // cannot evict synchronously must not turn authoritative cleanup into a
-        // false failure.
-    }
+    client.store?.removeRoom(roomId);
 }
 function isActiveMembership(membership) {
     return membership === "join" || membership === "invite";
@@ -582,12 +579,11 @@ function isRevocableMembership(membership) {
 }
 function safePartialDetail(error) {
     // Provider/Matrix errors can contain response bodies, URLs, or credentials.
-    // StorageError messages are authored by this package and are already
-    // bounded; retain those local policy details so callers still get useful
-    // owner/self-target diagnostics.
+    // StorageError messages are authored by this package; retain those local
+    // policy details so callers still get useful owner/self-target diagnostics.
     if (!(error instanceof StorageError) || error instanceof MutationOutcomeUnknownError)
         return undefined;
-    return error.message.length <= 256 ? error.message : undefined;
+    return error.message;
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
@@ -599,16 +595,12 @@ export async function createVault(storage, name, options) {
             tree = await withRateLimitRetry(() => storage.createTree(name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create vault failed");
+            throw new StorageError("create vault failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: tree.id, name };
@@ -646,7 +638,7 @@ export async function joinVault(storage, vaultId, options) {
                 membership = null;
             }
             else {
-                throw new StorageError("join failed");
+                throw new StorageError("join failed", { cause: err });
             }
         }
         if (membership === "join")
@@ -664,7 +656,7 @@ export async function joinVault(storage, vaultId, options) {
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("join failed");
+            throw new StorageError("join failed", { cause: err });
         }
         ensureOperationActive(signal);
         return { vaultId, joined: true };
@@ -700,8 +692,6 @@ export async function listPendingInvites(storage, options) {
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         const rooms = client.getRooms();
-        if (rooms.length > MAX_LIST_ITEMS)
-            throw new StorageError("invite list is too large");
         const invites = [];
         for (const room of rooms) {
             ensureOperationActive(signal);
@@ -820,7 +810,7 @@ export async function declineInvite(storage, vaultId, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("decline failed");
+            throw new StorageError("decline failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { vaultId, declined: true };
@@ -893,7 +883,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message === "share failed" ||
@@ -902,7 +892,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("share failed");
+                throw new StorageError("share failed", { cause: error });
             }
             return { vaultId, userId, role };
         }, operation.signal);
@@ -968,7 +958,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message.includes("owner") ||
@@ -976,7 +966,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("unshare failed");
+                throw new StorageError("unshare failed", { cause: error });
             }
             return { vaultId, userId, removed: true };
         }, operation.signal);
@@ -992,10 +982,10 @@ export async function listMembers(storage, vaultId, options) {
         try {
             return await withRateLimitRetry(() => storage.listMembers(tree, { signal }), signal);
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("list members failed");
+            throw new StorageError("list members failed", { cause: error });
         }
     });
 }
@@ -1008,16 +998,12 @@ export async function listFiles(storage, treeId, options) {
             const files = tree
                 .listFiles()
                 .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id));
-            if (files.length > MAX_LIST_ITEMS)
-                throw new StorageError("file list is too large");
             return files.map((f) => ({ id: f.id, name: f.getName() }));
         }
         catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            if (error instanceof StorageError && error.message === "file list is too large")
-                throw error;
-            throw new StorageError("list files failed");
+            throw new StorageError("list files failed", { cause: error });
         }
     });
 }
@@ -1030,8 +1016,6 @@ export async function listSubfolders(storage, parentId, options) {
         const directories = tree
             .getDirectories()
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
-        if (directories.length > MAX_LIST_ITEMS)
-            throw new StorageError("folder list is too large");
         return directories.map((d) => ({ id: d.id, name: d.room.name }));
     });
 }
@@ -1044,16 +1028,12 @@ export async function createSubfolder(storage, parentId, name, options) {
             sub = await withRateLimitRetry(() => storage.createSubtree(tree, name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create folder failed");
+            throw new StorageError("create folder failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: sub.id, name };
@@ -1071,12 +1051,7 @@ async function renameTree(storage, treeId, name, options) {
                 const current = storage.getTree(treeId);
                 if (current?.room.name === name)
                     return current;
-                try {
-                    await storage.refreshRoomState(treeId, { signal });
-                }
-                catch {
-                    return null;
-                }
+                await storage.refreshRoomState(treeId, { signal });
                 const refreshed = storage.getTree(treeId);
                 return refreshed?.room.name === name ? refreshed : null;
             }, { timeoutMs: 15000, signal });
@@ -1086,7 +1061,7 @@ async function renameTree(storage, treeId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename failed");
+            throw new StorageError("rename failed", { cause: error });
         }
         return { id: treeId, name };
     }, "mutation");
@@ -1132,13 +1107,9 @@ async function deleteTree(storage, treeId, options) {
                 graph = validateDeletionGraph(client, tree, ids, removedRooms);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError ||
-                    error instanceof MutationPartialError ||
-                    error instanceof NonEmptyTreeError)
-                    throw error;
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             // Keep external parent links intact until the room deletion succeeds.
             // Unlinking first would silently detach a live vault on failure.
@@ -1146,16 +1117,9 @@ async function deleteTree(storage, treeId, options) {
                 await unlinkExternalParents(storage, tree.id, graph.externalParents, operation.signal);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
-                if (error instanceof StorageError && error.message === "delete graph unlink cleanup is incomplete") {
-                    throw error;
-                }
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             try {
                 await deleteRoomDeterministically(storage, tree.id, operation.signal);
@@ -1167,16 +1131,14 @@ async function deleteTree(storage, treeId, options) {
                 try {
                     await relinkExternalParents(storage, tree.id, graph.externalParents, new AbortController().signal);
                 }
-                catch {
-                    throw new StorageError("delete cleanup is incomplete");
+                catch (cleanupError) {
+                    throw new StorageError("delete cleanup is incomplete", {
+                        cause: new AggregateError([error, cleanupError], "delete and external-parent relink both failed", { cause: error }),
+                    });
                 }
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             return { id: treeId, deleted: true };
         }, operation.signal);
@@ -1216,7 +1178,7 @@ export async function renameFile(storage, treeId, fileId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename file failed");
+            throw new StorageError("rename file failed", { cause: error });
         }
         return { id: fileId, name };
     }, "mutation");
@@ -1235,11 +1197,11 @@ async function resolveFileVersions(branch, signal) {
     try {
         history = await branch.getVersionHistory();
     }
-    catch {
-        throw new StorageError("could not resolve file version history safely");
+    catch (error) {
+        throw new StorageError("could not resolve file version history safely", { cause: error });
     }
-    if (!Array.isArray(history) || history.length === 0 || history.length > MAX_FILE_VERSION_CHAIN) {
-        throw new StorageError("file version history is invalid or too large");
+    if (!Array.isArray(history) || history.length === 0) {
+        throw new StorageError("file version history is invalid");
     }
     const eventIds = new Set();
     const mediaIds = new Set();
@@ -1253,8 +1215,8 @@ async function resolveFileVersions(branch, signal) {
         try {
             validateMatrixEventId(version.id, "file version event ID");
         }
-        catch {
-            throw new StorageError("file version history contains an invalid event ID");
+        catch (error) {
+            throw new StorageError("file version history contains an invalid event ID", { cause: error });
         }
         if (eventIds.has(version.id)) {
             throw new StorageError("file version history contains a cycle");
@@ -1264,17 +1226,14 @@ async function resolveFileVersions(branch, signal) {
         try {
             fileInfo = await version.getFileInfo();
         }
-        catch {
-            throw new StorageError("could not resolve encrypted file version safely");
+        catch (error) {
+            throw new StorageError("could not resolve encrypted file version safely", { cause: error });
         }
         const mediaId = fileInfo?.info?.url;
         if (typeof mediaId !== "string" || mediaId.length === 0) {
             throw new StorageError("encrypted file version has no media identifier");
         }
         mediaIds.add(mediaId);
-        if (mediaIds.size > MAX_FILE_VERSION_CHAIN) {
-            throw new StorageError("file media version history is too large");
-        }
         versions.push({ branch: version, mediaId });
     }
     return versions;
@@ -1297,7 +1256,7 @@ async function deleteFileMedia(storage, mediaIds, signal) {
             throw error;
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("delete file media failed");
+        throw new StorageError("delete file media failed", { cause: error });
     }
 }
 export async function deleteFile(storage, treeId, fileId, options) {
@@ -1322,9 +1281,9 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             if (signal.aborted) {
-                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled");
+                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled", { cause: error });
             }
-            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped");
+            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped", { cause: error });
         }
         try {
             await waitForCondition(async () => {
@@ -1338,7 +1297,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             const detail = "Matrix deletion completed but the inactive file state could not be verified";
-            throw new MutationPartialError("delete file", completedIds, detail);
+            throw new MutationPartialError("delete file", completedIds, detail, { cause: error });
         }
         for (const { branch: version } of versions) {
             markFileDeleted(storage.getClient(), tree.id, version.id);
@@ -1357,7 +1316,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("upload failed");
+            throw new StorageError("upload failed", { cause: error });
         });
         // The create-file request is acknowledged before the event necessarily
         // arrives in this client's sync timeline. A caller can otherwise report a
@@ -1376,7 +1335,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
         catch (error) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
-            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally");
+            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: fileId, name, mimetype };
@@ -1391,11 +1350,11 @@ export async function downloadFile(storage, treeId, fileId, options) {
             result = await storage.downloadFile(branch, signal);
         }
         catch (error) {
-            if (error instanceof UndecryptableFileError)
+            if (error instanceof StorageError)
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("download failed");
+            throw new StorageError("download failed", { cause: error });
         }
         ensureOperationActive(signal);
         return {
@@ -1425,41 +1384,21 @@ export async function getFileDetails(storage, treeId, fileId, options) {
         let size = null;
         let createdAt = null;
         let updatedAt = null;
-        try {
-            ensureOperationActive(signal);
-            const { info } = await branch.getFileInfo();
-            if (info) {
-                if (typeof info["mimetype"] === "string")
-                    mimetype = info["mimetype"];
-                if (typeof info["size"] === "number")
-                    size = info["size"];
-            }
-        }
-        catch {
-            if (signal.aborted)
-                throw new StorageError("operation cancelled");
-            // Partial metadata is fine — UI shows "—" for unknown fields.
-        }
         try {
             ensureOperationActive(signal);
             const event = await branch.getFileEvent();
-            const content = event.getContent();
-            const infoBlock = content["info"];
-            if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
-                mimetype = infoBlock["mimetype"];
-            }
-            if (size == null && typeof infoBlock?.["size"] === "number") {
-                size = infoBlock["size"];
-            }
-            const eventAny = event;
-            const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
-            createdAt = tsToIso(ts);
+            const metadata = readFileEventMetadata(event.getContent());
+            mimetype = metadata.mimetype;
+            size = metadata.size;
+            createdAt = tsToIso(event.getTs());
             updatedAt = createdAt;
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            // Same as above.
+            if (error instanceof StorageError)
+                throw error;
+            throw new StorageError("get file details failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { name, mimetype, size, createdAt, updatedAt };
@@ -1479,8 +1418,8 @@ async function getTreeDetails(storage, treeId, signal) {
         try {
             memberCount = room.getJoinedMemberCount();
         }
-        catch {
-            memberCount = null;
+        catch (error) {
+            throw new StorageError("member count lookup failed", { cause: error });
         }
     }
     return {

package/dist/core/poll.d.ts

@@ -1,3 +1,6 @@
+export declare class ConditionTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
 /**
  * A freshly-synced client doesn't always see a room/event the *instant* the
  * server has committed it — e.g. a room this same session just created can

package/dist/core/poll.js

@@ -1,3 +1,9 @@
+export class ConditionTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`timed out after ${timeoutMs}ms waiting for condition`);
+        this.name = "ConditionTimeoutError";
+    }
+}
 /**
  * A freshly-synced client doesn't always see a room/event the *instant* the
  * server has committed it — e.g. a room this same session just created can
@@ -12,7 +18,7 @@ export async function waitForCondition(check, opts) {
     const timeoutMs = opts?.timeoutMs ?? 15000;
     const intervalMs = opts?.intervalMs ?? 300;
     const deadline = Date.now() + timeoutMs;
-    const timeoutError = () => new Error(`timed out after ${timeoutMs}ms waiting for condition`);
+    const timeoutError = () => new ConditionTimeoutError(timeoutMs);
     const abortError = () => {
         const reason = opts?.signal?.reason;
         return reason instanceof Error ? reason : new Error("condition wait aborted");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.5.28",
+  "version": "0.5.29",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",