@telecrypt-io/storage 0.2.13 → 0.4.0

package/README.md

@@ -5,17 +5,16 @@
 End-to-end encrypted file storage and sharing, built on Matrix.
 
 Files are encrypted on the client before upload. The server stores only opaque ciphertext and
-never holds the decryption keys. Shared folders let multiple people add and read files, and a
+never holds the decryption keys. Shared vaults let multiple people add and read files, and a
 Recovery Key restores your files on a new device — even if you lose the original.
 
-**Status:** library source only. `@telecrypt-io/storage@0.2.5` is the current public release,
-published from this repository's protected `v0.2.5` tag with NPM Trusted Publishing/OIDC
-provenance. The older `0.1.3` release is the immutable legacy combined library-and-CLI package.
+This repository publishes the library package from protected exact-version tags with NPM Trusted
+Publishing/OIDC provenance. The command-line client is maintained in its own repository.
 
 ## Install
 
 ```bash
-npm install @telecrypt-io/storage@0.2.5
+npm install @telecrypt-io/storage@0.4.0
 ```
 
 This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
@@ -31,8 +30,8 @@ import * as core from "@telecrypt-io/storage/core";
 const storage = await TeleCryptIOStorage.create({
   baseUrl, userId, accessToken, deviceId,
 });
-const folder = await core.createFolder(storage, "Photos");
-await core.uploadFile(storage, folder.id, "cat.jpg", bytes, "image/jpeg");
+const vault = await core.createVault(storage, "Photos");
+await core.uploadFile(storage, vault.id, "cat.jpg", bytes, "image/jpeg");
 ```
 
 The command-line client is sourced by
@@ -45,10 +44,10 @@ application is sourced by
 Built on [MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), which models
 a file tree using Matrix primitives:
 
-| File-system concept | Matrix concept |
+| Storage concept | Matrix concept |
 |---|---|
-| Folder | A Space (room marked as a file tree) |
-| Subfolder | A child Space |
+| Vault | A Space (room marked as a file tree) |
+| Folder | A child Space |
 | File | An event pointing at encrypted uploaded content |
 | Version | A newer event superseding the old |
 | Sharing | Room invitation |
@@ -61,13 +60,13 @@ stock Synapse.
 ## Development
 
 ```bash
-npm install
-npm run synapse:up     # disposable local Synapse for tests
+npm ci
+npm run synapse:up     # disposable local Synapse/MAS fixture
 npm test
 npm run synapse:down
 ```
 
-Tests run against a real local Synapse in podman, never against a production server.
+Tests run against a real local Synapse/MAS fixture in Podman, never against a production server.
 
 See [RELEASING.md](./RELEASING.md) for the guarded npm release procedure.
 

package/dist/TeleCryptIOStorage.d.ts

@@ -194,7 +194,7 @@ export declare class TeleCryptIOStorage {
         }>;
     };
     /**
-     * Creates a new top-level shared folder (tree space).
+     * Creates a new top-level shared vault (tree space).
      *
      * Works around a genuine race in matrix-js-sdk's own
      * `unstableCreateFileTree()`: it creates the room via a plain
@@ -209,7 +209,7 @@ export declare class TeleCryptIOStorage {
      * how we get "Unknown room" at all); this method waits for the client's
      * own ongoing sync loop to surface it, then wraps it directly via
      * `unstableGetFileTreeSpace`, instead of surfacing a spurious failure for
-     * a folder that in fact exists.
+     * a vault that in fact exists.
      */
     createTree(name: string): Promise<TreeSpace>;
     listTrees(): Promise<TreeSpace[]>;
@@ -230,7 +230,7 @@ export declare class TeleCryptIOStorage {
     createSubtree(parent: TreeSpace, name: string): Promise<TreeSpace>;
     getTree(roomId: string): TreeSpace | null;
     /**
-     * Lists the participants of a shared folder (tree space) and their role,
+     * Lists the participants of a shared vault (tree space) and their role,
      * derived from room membership (join/invite state) + power levels.
      * Includes invited-but-not-yet-joined members as well as joined ones;
      * excludes anyone who has left/been kicked/banned.

package/dist/TeleCryptIOStorage.js

@@ -250,7 +250,7 @@ export class TeleCryptIOStorage {
         };
     }
     /**
-     * Creates a new top-level shared folder (tree space).
+     * Creates a new top-level shared vault (tree space).
      *
      * Works around a genuine race in matrix-js-sdk's own
      * `unstableCreateFileTree()`: it creates the room via a plain
@@ -265,7 +265,7 @@ export class TeleCryptIOStorage {
      * how we get "Unknown room" at all); this method waits for the client's
      * own ongoing sync loop to surface it, then wraps it directly via
      * `unstableGetFileTreeSpace`, instead of surfacing a spurious failure for
-     * a folder that in fact exists.
+     * a vault that in fact exists.
      */
     async createTree(name) {
         const knownRoomIdsBefore = new Set(this.client.getRooms().map((r) => r.roomId));
@@ -369,7 +369,7 @@ export class TeleCryptIOStorage {
         return this.client.unstableGetFileTreeSpace(roomId);
     }
     /**
-     * Lists the participants of a shared folder (tree space) and their role,
+     * Lists the participants of a shared vault (tree space) and their role,
      * derived from room membership (join/invite state) + power levels.
      * Includes invited-but-not-yet-joined members as well as joined ones;
      * excludes anyone who has left/been kicked/banned.
@@ -434,8 +434,7 @@ export class TeleCryptIOStorage {
             // of a useful error. Surface the real cause.
             throw new Error(`downloadFile: could not read file info from the event — it is likely undecryptable on this device (missing megolm session; try restoring from a Recovery Key)`);
         }
-        // Belt-and-braces: if a future matrix-js-sdk version returns a
-        // placeholder without throwing, still fail with the clear message.
+        // Also reject an incomplete placeholder if matrix-js-sdk returns one.
         if (!info || typeof info.url !== "string") {
             throw new Error("downloadFile: could not read file info from the event — it is likely undecryptable on this device (missing megolm session; try restoring from a Recovery Key)");
         }

package/dist/core/errors.d.ts

@@ -1,8 +1,7 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
- * shown directly to a user (CLI stderr today, a future UI's error toast
- * tomorrow) — never a raw stack trace. Thrown for expected failure
- * conditions (bad login, wrong recovery key, missing file/folder, not
+ * shown directly to a user — never a raw stack trace. Thrown for expected failure
+ * conditions (bad login, wrong recovery key, missing file, vault, or folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
-export declare class CliError extends Error {
+export declare class StorageError extends Error {
     constructor(message: string);
 }

package/dist/core/errors.js

@@ -1,11 +1,10 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
- * shown directly to a user (CLI stderr today, a future UI's error toast
- * tomorrow) — never a raw stack trace. Thrown for expected failure
- * conditions (bad login, wrong recovery key, missing file/folder, not
+ * shown directly to a user — never a raw stack trace. Thrown for expected failure
+ * conditions (bad login, wrong recovery key, missing file, vault, or folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
-export class CliError extends Error {
+export class StorageError extends Error {
     constructor(message) {
         super(message);
-        this.name = "CliError";
+        this.name = "StorageError";
     }
 }

package/dist/core/index.d.ts

@@ -1,5 +1,4 @@
-/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
- * needs — the typed result contract plus every operation. */
+/** The full platform-agnostic surface for user-facing clients. */
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";

package/dist/core/index.js

@@ -1,5 +1,4 @@
-/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
- * needs — the typed result contract plus every operation. */
+/** The full platform-agnostic surface for user-facing clients. */
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";

package/dist/core/oidc.d.ts

@@ -21,10 +21,8 @@ export interface OidcTokenSet {
     expiresAt?: number;
 }
 /**
- * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
- * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
- * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
- * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
+ * Matrix client's authentication metadata endpoint.
  *
  * NODE CALLERS: this internally constructs oidc-client-ts state that
  * requires `window.sessionStorage`/`window.localStorage` to exist (a real

package/dist/core/oidc.js

@@ -11,12 +11,10 @@
 import { createClient } from "matrix-js-sdk";
 import { registerOidcClient, generateScope, generateOidcAuthorizationUrl, completeAuthorizationCodeGrant, startDeviceAuthorization, waitForDeviceAuthorization, } from "matrix-js-sdk/lib/oidc/index.js";
 import { OidcClient, WebStorageStateStore } from "oidc-client-ts";
-import { CliError } from "./errors.js";
+import { StorageError } from "./errors.js";
 /**
- * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
- * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
- * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
- * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
+ * Matrix client's authentication metadata endpoint.
  *
  * NODE CALLERS: this internally constructs oidc-client-ts state that
  * requires `window.sessionStorage`/`window.localStorage` to exist (a real
@@ -31,7 +29,7 @@ export async function discoverOidcIssuer(homeserverBaseUrl) {
         return await client.getAuthMetadata();
     }
     catch (err) {
-        throw new CliError(`OIDC discovery failed: ${err.message}`);
+        throw new StorageError(`OIDC discovery failed: ${err.message}`);
     }
 }
 /**
@@ -44,7 +42,7 @@ export async function registerClient(authMetadata, metadata) {
         return await registerOidcClient(authMetadata, metadata);
     }
     catch (err) {
-        throw new CliError(`OIDC dynamic client registration failed: ${err.message}`);
+        throw new StorageError(`OIDC dynamic client registration failed: ${err.message}`);
     }
 }
 // ---------------------------------------------------------------------------
@@ -177,26 +175,26 @@ export async function refreshOidcToken(tokenEndpoint, clientId, refreshToken) {
     });
     if (!res.ok) {
         const body = await res.text();
-        throw new CliError(`OIDC token refresh failed (${res.status}): ${body}`);
+        throw new StorageError(`OIDC token refresh failed (${res.status}): ${body}`);
     }
     const data = await res.json();
     if (!data || typeof data !== "object") {
-        throw new CliError("OIDC token refresh returned an invalid response");
+        throw new StorageError("OIDC token refresh returned an invalid response");
     }
     const record = data;
     const accessToken = record.access_token;
     const nextRefreshToken = record.refresh_token;
     const expiresIn = record.expires_in;
     if (typeof accessToken !== "string" || accessToken.trim() === "") {
-        throw new CliError("OIDC token refresh returned no access token");
+        throw new StorageError("OIDC token refresh returned no access token");
     }
     if (nextRefreshToken !== undefined &&
         (typeof nextRefreshToken !== "string" || nextRefreshToken.trim() === "")) {
-        throw new CliError("OIDC token refresh returned an invalid refresh token");
+        throw new StorageError("OIDC token refresh returned an invalid refresh token");
     }
     if (expiresIn !== undefined &&
         (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn < 0)) {
-        throw new CliError("OIDC token refresh returned an invalid expiry");
+        throw new StorageError("OIDC token refresh returned an invalid expiry");
     }
     return {
         accessToken,

package/dist/core/operations.d.ts

@@ -3,50 +3,59 @@
  * taking an already-created `TeleCryptIOStorage` plus plain inputs and returning
  * one of the typed results in `./types.ts`. No I/O beyond the Matrix client
  * itself, no stdout, no `process`, no file paths — bytes in/out are always
- * `Uint8Array`. This is what the CLI's command actions call today and what
- * a future React UI calls directly, so both run the exact same tested logic
- * and share the exact same result shapes.
+ * `Uint8Array`. All callers run the same tested logic and share the same result
+ * shapes.
  *
  * `core/` never creates the `TeleCryptIOStorage`/`MatrixClient` itself — store
  * config (persistent crypto store, session credentials, etc.) is
- * platform-specific and stays with the caller (see `src/cli/storage.ts`).
+ * platform-specific and stays with the caller.
  */
 import { TeleCryptIOStorage } from "../TeleCryptIOStorage.js";
-import type { DownloadedFile, FileDetails, FileInfo, FolderDetails, FolderInfo, DeleteResult, JoinResult, Member, RecoveryRestore, RecoverySetup, RenameResult, ShareResult, UnshareResult } from "./types.js";
-export declare function createFolder(storage: TeleCryptIOStorage, name: string): Promise<FolderInfo>;
-/** Top-level folders only — excludes subdirectories of an existing tree. */
-export declare function listFolders(storage: TeleCryptIOStorage): Promise<FolderInfo[]>;
-/** Current account's effective role for a folder, or null while it is unavailable. */
-export declare function getMyFolderRole(storage: TeleCryptIOStorage, folderId: string): string | null;
-export declare function joinFolder(storage: TeleCryptIOStorage, folderId: string): Promise<JoinResult>;
+import type { DownloadedFile, FolderDetails, FolderInfo, FileDetails, FileInfo, VaultDetails, VaultInfo, DeleteResult, JoinResult, Member, RecoveryRestore, RecoverySetup, RenameResult, ShareResult, UnshareResult } from "./types.js";
+export declare function createVault(storage: TeleCryptIOStorage, name: string): Promise<VaultInfo>;
+/** Top-level vaults only — excludes subdirectories of an existing tree. */
+export declare function listVaults(storage: TeleCryptIOStorage): Promise<VaultInfo[]>;
+/** Current account's effective role for a vault, or null while it is unavailable. */
+export declare function getMyVaultRole(storage: TeleCryptIOStorage, vaultId: string): string | null;
+export declare function joinVault(storage: TeleCryptIOStorage, vaultId: string): Promise<JoinResult>;
 /** Rooms where this account is invited and the room looks like a file tree. */
-export declare function listPendingInvites(storage: TeleCryptIOStorage): Promise<FolderInfo[]>;
-/** Decline a folder invite (same as leaving before join). */
-export declare function declineInvite(storage: TeleCryptIOStorage, folderId: string): Promise<{
-    folderId: string;
+export declare function listPendingInvites(storage: TeleCryptIOStorage): Promise<VaultInfo[]>;
+/** Decline a vault invite (same as leaving before join). */
+export declare function declineInvite(storage: TeleCryptIOStorage, vaultId: string): Promise<{
+    vaultId: string;
     declined: boolean;
 }>;
 /**
- * Invites `userId` to the folder at `role` and applies the role's
+ * Invites `userId` to the vault at `role` and applies the role's
  * permissions. Doubles as "change an existing participant's role" (call
  * again with a different role): inviting someone who's already a member is
  * a 403 from the server, not a real failure — that specific error is
  * swallowed and the role change still applies. Any other invite failure
  * (e.g. unknown user) propagates.
  */
-export declare function shareFolder(storage: TeleCryptIOStorage, folderId: string, userId: string, role: string): Promise<ShareResult>;
-export declare function unshareFolder(storage: TeleCryptIOStorage, folderId: string, userId: string): Promise<UnshareResult>;
-export declare function listMembers(storage: TeleCryptIOStorage, folderId: string): Promise<Member[]>;
-export declare function listFiles(storage: TeleCryptIOStorage, folderId: string): Promise<FileInfo[]>;
-export declare function listSubfolders(storage: TeleCryptIOStorage, folderId: string): Promise<FolderInfo[]>;
-export declare function createSubfolder(storage: TeleCryptIOStorage, folderId: string, name: string): Promise<FolderInfo>;
+export declare function shareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string, role: string): Promise<ShareResult>;
+export declare function unshareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string): Promise<UnshareResult>;
+export declare function listMembers(storage: TeleCryptIOStorage, vaultId: string): Promise<Member[]>;
+export declare function listFiles(storage: TeleCryptIOStorage, treeId: string): Promise<FileInfo[]>;
+/** Lists the direct child folders of a vault or folder. */
+export declare function listSubfolders(storage: TeleCryptIOStorage, parentId: string): Promise<FolderInfo[]>;
+export declare function createSubfolder(storage: TeleCryptIOStorage, parentId: string, name: string): Promise<FolderInfo>;
+/** Renames a top-level Vault. */
+export declare function renameVault(storage: TeleCryptIOStorage, vaultId: string, name: string): Promise<RenameResult>;
+/** Renames a nested folder. */
 export declare function renameFolder(storage: TeleCryptIOStorage, folderId: string, name: string): Promise<RenameResult>;
+/** Deletes a top-level Vault. */
+export declare function deleteVault(storage: TeleCryptIOStorage, vaultId: string): Promise<DeleteResult>;
+/** Deletes a nested folder. */
 export declare function deleteFolder(storage: TeleCryptIOStorage, folderId: string): Promise<DeleteResult>;
-export declare function renameFile(storage: TeleCryptIOStorage, folderId: string, fileId: string, name: string): Promise<RenameResult>;
-export declare function deleteFile(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<DeleteResult>;
-export declare function uploadFile(storage: TeleCryptIOStorage, folderId: string, name: string, bytes: Uint8Array, mimetype: string): Promise<FileInfo>;
-export declare function downloadFile(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<DownloadedFile>;
+export declare function renameFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, name: string): Promise<RenameResult>;
+export declare function deleteFile(storage: TeleCryptIOStorage, treeId: string, fileId: string): Promise<DeleteResult>;
+export declare function uploadFile(storage: TeleCryptIOStorage, treeId: string, name: string, bytes: Uint8Array, mimetype: string): Promise<FileInfo>;
+export declare function downloadFile(storage: TeleCryptIOStorage, treeId: string, fileId: string): Promise<DownloadedFile>;
 export declare function setupRecovery(storage: TeleCryptIOStorage): Promise<RecoverySetup>;
 export declare function restoreRecovery(storage: TeleCryptIOStorage, recoveryKey: string): Promise<RecoveryRestore>;
-export declare function getFileDetails(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<FileDetails>;
+export declare function getFileDetails(storage: TeleCryptIOStorage, treeId: string, fileId: string): Promise<FileDetails>;
+/** Returns details for a top-level Vault. */
+export declare function getVaultDetails(storage: TeleCryptIOStorage, vaultId: string): Promise<VaultDetails>;
+/** Returns details for a nested folder. */
 export declare function getFolderDetails(storage: TeleCryptIOStorage, folderId: string): Promise<FolderDetails>;

package/dist/core/operations.js

@@ -1,4 +1,4 @@
-import { CliError } from "./errors.js";
+import { StorageError } from "./errors.js";
 import { waitForCondition } from "./poll.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
@@ -17,7 +17,7 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
-async function withRateLimitRetry(label, operation) {
+async function withRateLimitRetry(operation) {
     for (let attempt = 0;; attempt++) {
         try {
             return await operation();
@@ -43,61 +43,61 @@ async function withRateLimitRetry(label, operation) {
     }
 }
 /**
- * Resolves a folder by ID, polling briefly: a room this same account just
+ * Resolves a vault or folder by ID, polling briefly: a room this same account just
  * created (or was just invited to, by another process/session) can be
  * momentarily absent from a from-scratch `/sync` before showing up moments
  * later — real async settling, not an instant "not found". Throws a clean
- * error if the folder still isn't visible once the poll times out.
+ * error if the storage tree still isn't visible once the poll times out.
  */
-async function resolveTree(storage, folderId) {
+async function resolveTree(storage, treeId) {
     try {
-        return await waitForCondition(() => storage.getTree(folderId), {
+        return await waitForCondition(() => storage.getTree(treeId), {
             timeoutMs: 15000,
         });
     }
     catch {
-        throw new CliError(`folder not found: ${folderId}`);
+        throw new StorageError(`storage space not found: ${treeId}`);
     }
 }
 /** As `resolveTree`, but for a specific file within an already-resolved
- * folder — covers the same settling window for a file another
+ * vault or folder — covers the same settling window for a file another
  * process/session just uploaded. */
 async function resolveFile(tree, fileId) {
     try {
         return await waitForCondition(() => tree.getFile(fileId), { timeoutMs: 15000 });
     }
     catch {
-        throw new CliError(`file not found: ${fileId}`);
+        throw new StorageError(`file not found: ${fileId}`);
     }
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
-export async function createFolder(storage, name) {
-    const tree = await withRateLimitRetry("createFolder", () => storage.createTree(name));
+export async function createVault(storage, name) {
+    const tree = await withRateLimitRetry(() => storage.createTree(name));
     return { id: tree.id, name };
 }
-/** Top-level folders only — excludes subdirectories of an existing tree. */
-export async function listFolders(storage) {
+/** Top-level vaults only — excludes subdirectories of an existing tree. */
+export async function listVaults(storage) {
     const trees = await storage.listTrees();
     return trees.filter((t) => t.isTopLevel).map((t) => ({ id: t.id, name: t.room.name }));
 }
-/** Current account's effective role for a folder, or null while it is unavailable. */
-export function getMyFolderRole(storage, folderId) {
+/** Current account's effective role for a vault, or null while it is unavailable. */
+export function getMyVaultRole(storage, vaultId) {
     const userId = storage.getClient().getUserId();
-    const tree = storage.getTree(folderId);
+    const tree = storage.getTree(vaultId);
     if (!userId || !tree)
         return null;
     return tree.getPermissions(userId);
 }
-export async function joinFolder(storage, folderId) {
+export async function joinVault(storage, vaultId) {
     try {
-        await withRateLimitRetry("joinFolder", () => storage.getClient().joinRoom(folderId));
+        await withRateLimitRetry(() => storage.getClient().joinRoom(vaultId));
     }
     catch (err) {
-        throw new CliError(`join failed: ${err.message}`);
+        throw new StorageError(`join failed: ${err.message}`);
     }
-    return { folderId, joined: true };
+    return { vaultId, joined: true };
 }
 function roomDisplayName(storage, roomId, fallbackName) {
     const client = storage.getClient();
@@ -140,106 +140,123 @@ export async function listPendingInvites(storage) {
     }
     return invites;
 }
-/** Decline a folder invite (same as leaving before join). */
-export async function declineInvite(storage, folderId) {
+/** Decline a vault invite (same as leaving before join). */
+export async function declineInvite(storage, vaultId) {
     const client = storage.getClient();
     try {
-        await withRateLimitRetry("declineInvite", async () => {
-            await client.leave(folderId);
+        await withRateLimitRetry(async () => {
+            await client.leave(vaultId);
             // The server only allows forgetting a room once this account's
             // membership is `leave`; forgetting removes the room from the local
             // store immediately, so a declined invite stops showing up in
-            // listFolders/listPendingInvites without waiting for the leave event
+            // listVaults/listPendingInvites without waiting for the leave event
             // to round-trip through the background sync loop.
-            await client.forget(folderId);
+            await client.forget(vaultId);
         });
     }
     catch (err) {
-        throw new CliError(`decline failed: ${err.message}`);
+        throw new StorageError(`decline failed: ${err.message}`);
     }
-    return { folderId, declined: true };
+    return { vaultId, declined: true };
 }
 /**
- * Invites `userId` to the folder at `role` and applies the role's
+ * Invites `userId` to the vault at `role` and applies the role's
  * permissions. Doubles as "change an existing participant's role" (call
  * again with a different role): inviting someone who's already a member is
  * a 403 from the server, not a real failure — that specific error is
  * swallowed and the role change still applies. Any other invite failure
  * (e.g. unknown user) propagates.
  */
-export async function shareFolder(storage, folderId, userId, role) {
+export async function shareVault(storage, vaultId, userId, role) {
     if (role !== "viewer" && role !== "editor") {
-        throw new CliError(`invalid --role "${role}" (must be viewer or editor)`);
+        throw new StorageError(`invalid --role "${role}" (must be viewer or editor)`);
     }
-    const tree = await resolveTree(storage, folderId);
+    const tree = await resolveTree(storage, vaultId);
     try {
-        await withRateLimitRetry("shareFolder.invite", () => tree.invite(userId));
+        await withRateLimitRetry(() => tree.invite(userId));
     }
     catch (err) {
         if (!/already in the room/i.test(err.message)) {
             throw err;
         }
     }
-    await withRateLimitRetry("shareFolder.setPermissions", () => tree.setPermissions(userId, role));
-    return { folderId, userId, role };
+    await withRateLimitRetry(() => tree.setPermissions(userId, role));
+    return { vaultId, userId, role };
 }
-export async function unshareFolder(storage, folderId, userId) {
-    await resolveTree(storage, folderId);
+export async function unshareVault(storage, vaultId, userId) {
+    await resolveTree(storage, vaultId);
     try {
-        await withRateLimitRetry("unshareFolder", () => storage.getClient().kick(folderId, userId, "unshared"));
+        await withRateLimitRetry(() => storage.getClient().kick(vaultId, userId, "unshared"));
     }
     catch (err) {
-        throw new CliError(`unshare failed: ${err.message}`);
+        throw new StorageError(`unshare failed: ${err.message}`);
     }
-    return { folderId, userId, removed: true };
+    return { vaultId, userId, removed: true };
 }
-export async function listMembers(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    return withRateLimitRetry("listMembers", () => storage.listMembers(tree));
+export async function listMembers(storage, vaultId) {
+    const tree = await resolveTree(storage, vaultId);
+    return withRateLimitRetry(() => storage.listMembers(tree));
 }
-export async function listFiles(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    await storage.refreshRoomState(folderId);
+export async function listFiles(storage, treeId) {
+    const tree = await resolveTree(storage, treeId);
+    await storage.refreshRoomState(treeId);
     return tree.listFiles().map((f) => ({ id: f.id, name: f.getName() }));
 }
-export async function listSubfolders(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
+/** Lists the direct child folders of a vault or folder. */
+export async function listSubfolders(storage, parentId) {
+    const tree = await resolveTree(storage, parentId);
     return tree.getDirectories().map((d) => ({ id: d.id, name: d.room.name }));
 }
-export async function createSubfolder(storage, folderId, name) {
-    const tree = await resolveTree(storage, folderId);
-    const sub = await withRateLimitRetry("createSubfolder", () => storage.createSubtree(tree, name));
+export async function createSubfolder(storage, parentId, name) {
+    const tree = await resolveTree(storage, parentId);
+    const sub = await withRateLimitRetry(() => storage.createSubtree(tree, name));
     return { id: sub.id, name };
 }
+async function renameTree(storage, treeId, name) {
+    const tree = await resolveTree(storage, treeId);
+    await withRateLimitRetry(() => tree.setName(name));
+    return { id: treeId, name };
+}
+/** Renames a top-level Vault. */
+export async function renameVault(storage, vaultId, name) {
+    return renameTree(storage, vaultId, name);
+}
+/** Renames a nested folder. */
 export async function renameFolder(storage, folderId, name) {
-    const tree = await resolveTree(storage, folderId);
-    await withRateLimitRetry("renameFolder", () => tree.setName(name));
-    return { id: folderId, name };
+    return renameTree(storage, folderId, name);
 }
-export async function deleteFolder(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
+async function deleteTree(storage, treeId) {
+    const tree = await resolveTree(storage, treeId);
     // `tree.delete()` kicks members and leaves this room AND every
     // subdirectory room, but never forgets any of them, so they all linger in
-    // the local store and listFolders keeps returning the deleted folder until
+    // the local store and tree listings keep returning the deleted tree until
     // the leave events round-trip through the background sync loop (30-60s
     // under full-suite load). Forgetting removes each room from the local
     // store immediately; the server only accepts a forget once membership is
     // `leave`, which `tree.delete()` has just completed for the whole tree.
     const subdirectoryIds = tree.getDirectories().map((d) => d.id);
     const client = storage.getClient();
-    await withRateLimitRetry("deleteFolder", async () => {
+    await withRateLimitRetry(async () => {
         await tree.delete();
-        await client.forget(folderId);
+        await client.forget(treeId);
         for (const subId of subdirectoryIds) {
             await client.forget(subId);
         }
     });
-    return { id: folderId, deleted: true };
+    return { id: treeId, deleted: true };
+}
+/** Deletes a top-level Vault. */
+export async function deleteVault(storage, vaultId) {
+    return deleteTree(storage, vaultId);
+}
+/** Deletes a nested folder. */
+export async function deleteFolder(storage, folderId) {
+    return deleteTree(storage, folderId);
 }
-export async function renameFile(storage, folderId, fileId, name) {
-    const tree = await resolveTree(storage, folderId);
+export async function renameFile(storage, treeId, fileId, name) {
+    const tree = await resolveTree(storage, treeId);
     const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry("renameFile", () => branch.setName(name));
+    await withRateLimitRetry(() => branch.setName(name));
     // `setName` resolves when the homeserver accepts the state event, but a
     // fresh CLI/UI process can still read the previous local room state for a
     // short time. Do not report success until this client has observed the new
@@ -250,26 +267,26 @@ export async function renameFile(storage, folderId, fileId, name) {
     }, { timeoutMs: 15000 });
     return { id: fileId, name };
 }
-export async function deleteFile(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
+export async function deleteFile(storage, treeId, fileId) {
+    const tree = await resolveTree(storage, treeId);
     const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry("deleteFile", () => branch.delete());
+    await withRateLimitRetry(() => branch.delete());
     return { id: fileId, deleted: true };
 }
-export async function uploadFile(storage, folderId, name, bytes, mimetype) {
-    const tree = await resolveTree(storage, folderId);
-    const fileId = await withRateLimitRetry("uploadFile", () => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype));
+export async function uploadFile(storage, treeId, name, bytes, mimetype) {
+    const tree = await resolveTree(storage, treeId);
+    const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype));
     return { id: fileId, name, mimetype };
 }
-export async function downloadFile(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
+export async function downloadFile(storage, treeId, fileId) {
+    const tree = await resolveTree(storage, treeId);
     const branch = await resolveFile(tree, fileId);
     let result;
     try {
         result = await storage.downloadFile(branch);
     }
     catch (err) {
-        throw new CliError(`download failed: ${err.message}`);
+        throw new StorageError(`download failed: ${err.message}`);
     }
     return {
         bytes: new Uint8Array(result.data),
@@ -288,8 +305,8 @@ function tsToIso(ts) {
         return null;
     return new Date(ts).toISOString();
 }
-export async function getFileDetails(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
+export async function getFileDetails(storage, treeId, fileId) {
+    const tree = await resolveTree(storage, treeId);
     const branch = await resolveFile(tree, fileId);
     const name = branch.getName();
     let mimetype = null;
@@ -328,10 +345,10 @@ export async function getFileDetails(storage, folderId, fileId) {
     }
     return { name, mimetype, size, createdAt, updatedAt };
 }
-export async function getFolderDetails(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
+async function getTreeDetails(storage, treeId) {
+    const tree = await resolveTree(storage, treeId);
     const client = storage.getClient();
-    const room = client.getRoom(folderId);
+    const room = client.getRoom(treeId);
     let createdAt = null;
     let memberCount = null;
     if (room) {
@@ -345,9 +362,17 @@ export async function getFolderDetails(storage, folderId) {
         }
     }
     return {
-        name: tree.room.name || roomDisplayName(storage, folderId),
-        id: folderId,
+        name: tree.room.name || roomDisplayName(storage, treeId),
+        id: treeId,
         createdAt,
         memberCount,
     };
 }
+/** Returns details for a top-level Vault. */
+export async function getVaultDetails(storage, vaultId) {
+    return getTreeDetails(storage, vaultId);
+}
+/** Returns details for a nested folder. */
+export async function getFolderDetails(storage, folderId) {
+    return getTreeDetails(storage, folderId);
+}

package/dist/core/types.d.ts

@@ -1,12 +1,9 @@
-/**
- * The shared typed result contract for every `core/operations.ts` function.
- * This is deliberately the ONE definition of these shapes: the CLI's
- * `--json` schema is these types (or a trivial projection of them, e.g.
- * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
- * command output), and the future React UI's data model is these types
- * directly. Keeping it here means the CLI and the UI can never drift apart
- * on what an operation returns.
- */
+/** The typed result contract for every `core/operations.ts` function. */
+export interface VaultInfo {
+    id: string;
+    name: string;
+}
+/** A nested directory node inside a vault. */
 export interface FolderInfo {
     id: string;
     name: string;
@@ -22,17 +19,17 @@ export interface Member {
     membership: string;
 }
 export interface ShareResult {
-    folderId: string;
+    vaultId: string;
     userId: string;
     role: string;
 }
 export interface UnshareResult {
-    folderId: string;
+    vaultId: string;
     userId: string;
     removed: boolean;
 }
 export interface JoinResult {
-    folderId: string;
+    vaultId: string;
     joined: boolean;
 }
 export interface DeleteResult {
@@ -63,6 +60,13 @@ export interface FileDetails {
     createdAt: string | null;
     updatedAt: string | null;
 }
+export interface VaultDetails {
+    name: string;
+    id: string;
+    createdAt: string | null;
+    memberCount: number | null;
+}
+/** Details for a nested directory node inside a vault. */
 export interface FolderDetails {
     name: string;
     id: string;

package/dist/core/types.js

@@ -1,10 +1,2 @@
-/**
- * The shared typed result contract for every `core/operations.ts` function.
- * This is deliberately the ONE definition of these shapes: the CLI's
- * `--json` schema is these types (or a trivial projection of them, e.g.
- * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
- * command output), and the future React UI's data model is these types
- * directly. Keeping it here means the CLI and the UI can never drift apart
- * on what an operation returns.
- */
+/** The typed result contract for every `core/operations.ts` function. */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.2.13",
+  "version": "0.4.0",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "dist/index.js",