@meistrari/vault-sdk 1.7.0 → 1.8.1

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { GetUploadUrlResponseV2, GetDownloadUrlResponse } from '@meistrari/vault-shared/schemas';
 import { fileTypeFromBlob } from '@meistrari/file-type';
 import { lookup } from 'mime-types';
+import vaultUtils from '@meistrari/vault-shared/utils';
 
 var __defProp$2 = Object.defineProperty;
 var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -180,7 +181,7 @@ async function getFileHash(blob) {
 }
 async function detectFileMimeType(blob) {
   if (blob instanceof Blob && blob.type) {
-    return blob.type;
+    return blob.type.split(";")[0].trim();
   }
   if ("name" in blob && typeof blob.name === "string") {
     const extension = blob.name.split(".").pop()?.toLowerCase();
@@ -217,9 +218,20 @@ async function detectFileMimeType(blob) {
   }
   return void 0;
 }
+function basename(name, separator = "/") {
+  if (!name)
+    return void 0;
+  return name.substring(name.lastIndexOf(separator) + 1);
+}
+function getFileName(content) {
+  if ("name" in content && typeof content.name === "string") {
+    return basename(content.name);
+  }
+  return void 0;
+}
 
 const name = "@meistrari/vault-sdk";
-const version = "1.7.0";
+const version = "1.8.1";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -288,9 +300,6 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 const compatibilityDate = "2025-05-19";
-function removeVaultPrefix(url) {
-  return url.replace("vault://", "");
-}
 function detectMimeTypeFromFilename(filename) {
   const extension = filename.split(".").pop()?.toLowerCase();
   if (extension) {
@@ -397,6 +406,7 @@ class VaultFile {
    * @param metadata - The metadata for creating a file
    * @param metadata.size - The size of the file
    * @param metadata.mimeType - The mime type of the file
+   * @param metadata.parentId - The ID of the parent file for hierarchical file relationships
    * @param options - The options for the request
    * @param options.signal - The signal to abort the request
    *
@@ -409,7 +419,9 @@ class VaultFile {
       method: "POST",
       path: `files`,
       body: JSON.stringify({
-        ...metadata,
+        size: metadata.size,
+        mimeType: metadata.mimeType,
+        parentId: metadata.parentId,
         fileName: this.name,
         sha256sum: this.id ?? this.metadata?.id ?? (this.content ? await getFileHash(this.content) : void 0)
       }),
@@ -466,7 +478,7 @@ class VaultFile {
     const { reference, config: vaultConfig, download = false } = params;
     const config = resolveConfig(vaultConfig);
     const { vaultUrl, authStrategy } = config;
-    const id = removeVaultPrefix(reference);
+    const id = vaultUtils.file.getFileIdFromVaultReference(reference);
     const url = new URL(`files/${id}`, config.vaultUrl);
     const response = await wrappedFetch(url, {
       method: "GET",
@@ -497,7 +509,9 @@ class VaultFile {
    * @param params.name - The name of the file
    * @param params.content - The content of the file
    * @param params.config - The configuration for the VaultFile
+   * @param params.mimeType - The MIME type of the file (optional)
    * @param params.upload - Whether to upload the file (default: false)
+   * @param params.parentId - The ID of the parent file for hierarchical file relationships
    * @param options - The options for the request
    * @param options.signal - The signal to abort the request
    *
@@ -532,13 +546,30 @@ class VaultFile {
    *     upload: true
    * })
    * ```
+   *
+   * @example
+   * ```ts
+   * // Create a child file with a parent
+   * const file = new File(['content'], 'child.txt')
+   * const vaultFile = await VaultFile.fromContent({
+   *     name: 'child.txt',
+   *     content: file,
+   *     parentId: 'parent-file-id',
+   *     config: {
+   *         vaultUrl,
+   *         authStrategy,
+   *     },
+   *     upload: true
+   * })
+   * ```
    */
   static async fromContent(params, options) {
-    const { name, content, config: vaultConfig, upload = false } = params;
+    const { content, config: vaultConfig, upload = false, parentId } = params;
+    const name = basename(params.name) ?? getFileName(content);
     const config = resolveConfig(vaultConfig);
     const { vaultUrl, authStrategy } = config;
     const sha256sum = await getFileHash(content);
-    const mimeType = await detectFileMimeType(content);
+    const mimeType = params.mimeType ?? await detectFileMimeType(content);
     const size = content.size;
     const file = new VaultFile({
       content,
@@ -551,7 +582,8 @@ class VaultFile {
     });
     const createdFile = await file._createFile({
       size,
-      mimeType
+      mimeType,
+      parentId
     }, { signal: options?.signal });
     if (upload) {
       await file.upload(file.content, createdFile.uploadUrl, { signal: options?.signal });
@@ -567,6 +599,7 @@ class VaultFile {
    * @param params.contentLength - The size of the content in bytes
    * @param params.config - The configuration for the VaultFile
    * @param params.contentType - The MIME type of the content (optional)
+   * @param params.parentId - The ID of the parent file for hierarchical file relationships
    * @param options - The options for the request
    * @param options.signal - The signal to abort the request
    *
@@ -589,25 +622,66 @@ class VaultFile {
    *     contentType: file.type
    * })
    * ```
+   *
+   * @example
+   * ```ts
+   * // Create a child file with streaming
+   * const vaultFile = await VaultFile.fromStream({
+   *     name: 'child-video.mp4',
+   *     contentLength: 50 * 1024 * 1024,
+   *     contentType: 'video/mp4',
+   *     parentId: 'parent-file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * ```
    */
   static async fromStream(params, options) {
-    const { name, contentLength, config: vaultConfig, contentType } = params;
+    const { contentLength, config: vaultConfig, contentType, parentId } = params;
+    const name = basename(params.name);
     const config = resolveConfig(vaultConfig);
     const file = new VaultFile({ config, name });
     await file._createFile({
       size: contentLength,
-      mimeType: contentType || "application/octet-stream"
+      mimeType: contentType || "application/octet-stream",
+      parentId
     }, { signal: options?.signal });
     return file;
   }
   /**
-   * Populates the metadata of the file instance.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * Fetches and populates the metadata fields for this VaultFile instance.
+   *
+   * This method retrieves the file's metadata from the vault server and updates the instance's
+   * metadata, name, and id properties. Useful when you have a VaultFile instance that was created
+   * without full metadata or when you need to refresh the metadata.
    *
-   * @returns The file instance
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @returns The VaultFile instance with populated metadata (for method chaining)
    * @throws {Error} If the file ID is not set
    * @throws {FetchError} If the metadata fetch fails
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * await vaultFile.populateMetadata()
+   * console.log('File size:', vaultFile.metadata?.size)
+   * console.log('MIME type:', vaultFile.metadata?.mimeType)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Chain with other operations
+   * const file = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * await file.populateMetadata()
+   * const children = await file.getChildren()
+   * ```
    */
   async populateMetadata(options) {
     try {
@@ -620,10 +694,38 @@ class VaultFile {
     }
   }
   /**
-   * Gets the vault reference for this file.
+   * Returns the vault URI reference for this file.
+   *
+   * The vault reference is a URI in the format `vault://{fileId}` that can be used to
+   * uniquely identify and retrieve this file from the vault. This reference can be stored
+   * in databases, passed to other services, or used with {@link VaultFile.fromVaultReference}
+   * to reconstruct a VaultFile instance.
    *
-   * @returns The vault reference in the format `vault://{fileId}`
+   * @returns The vault reference string in the format `vault://{fileId}`
    * @throws {Error} If the file ID is not set
+   *
+   * @example
+   * ```ts
+   * const file = await VaultFile.fromContent({
+   *     name: 'document.txt',
+   *     content: new Blob(['content']),
+   *     config: { vaultUrl, authStrategy },
+   *     upload: true
+   * })
+   * const reference = file.getVaultReference()
+   * // Returns: "vault://abc123..."
+   * // Store this reference in your database for later retrieval
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Retrieve a file later using the reference
+   * const storedReference = database.get('file_reference')
+   * const file = await VaultFile.fromVaultReference({
+   *     reference: storedReference,
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * ```
    */
   getVaultReference() {
     if (!this.id) {
@@ -632,13 +734,37 @@ class VaultFile {
     return `vault://${this.id}`;
   }
   /**
-   * Fetches the metadata of the file.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * Fetches the complete metadata for this file from the vault server.
    *
-   * @returns The metadata of the file
+   * Retrieves detailed information about the file including size, MIME type, creation date,
+   * workspace ID, and other metadata fields. Unlike {@link populateMetadata}, this method
+   * returns the metadata without modifying the VaultFile instance.
+   *
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @returns A Promise that resolves to the FileMetadata object
    * @throws {Error} If the file ID is not set
    * @throws {FetchError} If the metadata fetch fails
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const metadata = await vaultFile.getFileMetadata()
+   * console.log('File size:', metadata.size)
+   * console.log('Created at:', metadata.createdAt)
+   * console.log('Workspace:', metadata.workspaceId)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Use with abort signal
+   * const controller = new AbortController()
+   * const metadata = await vaultFile.getFileMetadata({ signal: controller.signal })
+   * ```
    */
   async getFileMetadata(options) {
     if (!this.id) {
@@ -652,14 +778,41 @@ class VaultFile {
     return response;
   }
   /**
-   * Fetches a upload URL for the file.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
-   * @param options.expiresIn - The number of seconds the upload URL will be valid for
+   * Retrieves a presigned upload URL for uploading file content to the vault.
+   *
+   * This method returns a temporary URL that can be used to upload the file content directly
+   * to cloud storage (e.g., S3). The URL is cached and reused if still valid. If the file
+   * doesn't exist yet, it will be created automatically.
    *
-   * @returns The upload URL for the file
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   * @param options.expiresIn - Number of seconds the upload URL should be valid for (default: server-defined)
+   *
+   * @returns A Promise that resolves to a URL object for uploading the file
    * @throws {Error} If the vault service returns an invalid response
    * @throws {FetchError} If the upload URL fetch fails
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromContent({
+   *     name: 'document.txt',
+   *     content: new Blob(['content']),
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const uploadUrl = await vaultFile.getUploadUrl()
+   * // Use the URL for custom upload logic
+   * await fetch(uploadUrl, {
+   *     method: 'PUT',
+   *     body: file,
+   *     headers: { 'Content-Type': 'text/plain' }
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Request a longer-lived upload URL
+   * const uploadUrl = await vaultFile.getUploadUrl({ expiresIn: 7200 }) // 2 hours
+   * ```
    */
   async getUploadUrl(options) {
     if (this.lastUploadUrl && this.lastUploadUrl.expiresAt > /* @__PURE__ */ new Date()) {
@@ -686,15 +839,38 @@ class VaultFile {
     return this.lastUploadUrl.url;
   }
   /**
-   * Fetches a download URL for the file.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
-   * @param options.expiresIn - The number of seconds the download URL will be valid for
+   * Retrieves a presigned download URL for accessing the file content.
+   *
+   * This method returns a temporary URL that can be used to download the file content directly
+   * from cloud storage (e.g., S3). The URL is cached and reused if still valid. This is useful
+   * for generating shareable links or implementing custom download logic.
    *
-   * @returns The download URL for the file
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   * @param options.expiresIn - Number of seconds the download URL should be valid for (default: server-defined)
+   *
+   * @returns A Promise that resolves to a URL object for downloading the file
    * @throws {Error} If the vault service returns an invalid response
-   * @throws {Error} If not file ID, name or content is set
+   * @throws {Error} If no file ID, name, or content is set
    * @throws {FetchError} If the download URL fetch fails
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const downloadUrl = await vaultFile.getDownloadUrl()
+   * // Use the URL to download the file
+   * window.location.href = downloadUrl.toString()
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Request a longer-lived download URL
+   * const downloadUrl = await vaultFile.getDownloadUrl({ expiresIn: 3600 }) // 1 hour
+   * // Share this URL with others
+   * ```
    */
   async getDownloadUrl(options) {
     if (this.lastDownloadUrl && this.lastDownloadUrl.expiresAt > /* @__PURE__ */ new Date()) {
@@ -714,30 +890,51 @@ class VaultFile {
     return this.lastDownloadUrl.url;
   }
   /**
-   * Uploads a file to the vault.
+   * Uploads file content to the vault using a presigned URL.
+   *
+   * This method handles the actual file upload to cloud storage. If no file is provided,
+   * it uses the content from the VaultFile instance. If no upload URL is provided, one
+   * will be fetched automatically. The MIME type is detected automatically if not already set.
+   *
+   * @param file - The Blob or File to upload. If not provided, uses the instance's content property
+   * @param url - A presigned upload URL. If not provided, will be fetched via {@link getUploadUrl}
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the upload
+   *
+   * @throws {Error} If no file content is available (neither provided nor in the instance)
+   * @throws {FetchError} If the upload request fails
+   * @returns A Promise that resolves when the upload completes successfully
    *
    * @example
    * ```ts
+   * // Simple upload using instance content
    * const file = new File(['content'], 'document.txt')
    * const vaultFile = await VaultFile.fromContent({
    *     name: 'document.txt',
    *     content: file,
-   *     config: {
-   *         vaultUrl,
-   *         authStrategy,
-   *     },
+   *     config: { vaultUrl, authStrategy }
    * })
-   * await vaultFile.upload(file)
+   * await vaultFile.upload()
    * ```
    *
-   * @param file - The file to upload to the vault. If not provided, the file content will be taken from the `content` property.
-   * @param url - The URL to upload the file to. If not provided, the upload URL will be fetched from the vault.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * @example
+   * ```ts
+   * // Upload different content than what's in the instance
+   * const vaultFile = await VaultFile.fromContent({
+   *     name: 'document.txt',
+   *     content: new Blob(['original']),
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const newContent = new Blob(['updated content'])
+   * await vaultFile.upload(newContent)
+   * ```
    *
-   * @throws {FetchError} If the upload fails
-   * @throws {Error} If the file content is not set and no file is provided
-   * @returns Promise that resolves when upload is complete
+   * @example
+   * ```ts
+   * // Upload with custom URL (advanced usage)
+   * const uploadUrl = await vaultFile.getUploadUrl({ expiresIn: 3600 })
+   * await vaultFile.upload(file, uploadUrl.toString())
+   * ```
    */
   async upload(file, url, options) {
     const content = file ?? this.content;
@@ -768,31 +965,60 @@ class VaultFile {
     return await blobToBase64(blob);
   }
   /**
-   * Downloads a file from the vault as a stream for memory-efficient processing.
+   * Downloads the file as a ReadableStream for memory-efficient processing of large files.
    *
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * This method is ideal for handling large files without loading the entire content into memory.
+   * The stream can be processed chunk-by-chunk, piped to other streams, or saved incrementally.
+   * This is the recommended approach for files larger than a few megabytes.
    *
-   * @returns A ReadableStream that yields chunks of the file data
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the download
+   *
+   * @returns A Promise resolving to a ReadableStream that yields Uint8Array chunks
+   * @throws {Error} If the response body is not readable
+   * @throws {FetchError} If the download fails
    *
    * @example
    * ```ts
-   * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+   * // Process large file chunk by chunk
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://large-video-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
    * const stream = await vaultFile.downloadStream()
    *
-   * // Process the stream chunk by chunk
    * const reader = stream.getReader()
+   * let bytesReceived = 0
    * try {
    *     while (true) {
    *         const { done, value } = await reader.read()
    *         if (done) break
-   *         // Process the chunk (Uint8Array)
-   *         console.log('Received chunk of size:', value.length)
+   *         bytesReceived += value.length
+   *         console.log(`Downloaded ${bytesReceived} bytes...`)
+   *         // Process chunk (value is Uint8Array)
    *     }
    * } finally {
    *     reader.releaseLock()
    * }
    * ```
+   *
+   * @example
+   * ```ts
+   * // Pipe stream to a writable destination
+   * const stream = await vaultFile.downloadStream()
+   * const fileHandle = await navigator.storage.getDirectory()
+   *     .then(dir => dir.getFileHandle('output.dat', { create: true }))
+   * const writable = await fileHandle.createWritable()
+   * await stream.pipeTo(writable)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Use with abort signal
+   * const controller = new AbortController()
+   * const stream = await vaultFile.downloadStream({ signal: controller.signal })
+   * // Later: controller.abort()
+   * ```
    */
   async downloadStream(options) {
     const downloadUrl = await this.getDownloadUrl({ signal: options?.signal });
@@ -806,32 +1032,64 @@ class VaultFile {
     return response.body;
   }
   /**
-   * Uploads a file to the vault using a stream for memory-efficient processing.
+   * Uploads file content using a ReadableStream for memory-efficient processing of large files.
    *
-   * @param stream - The readable stream of file data to upload
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
-   * @param options.contentLength - The total size of the content (required for S3 uploads)
-   * @param options.contentType - The MIME type of the content (will be detected if not provided)
+   * This method is ideal for uploading large files without loading the entire content into memory.
+   * The stream is sent directly to cloud storage, making it perfect for files larger than a few
+   * megabytes. Note: When using Bun, the stream is buffered due to implementation limitations.
+   *
+   * @param stream - A ReadableStream of Uint8Array chunks containing the file data
+   * @param options - Required options for the upload
+   * @param options.contentLength - The total size of the content in bytes (required for S3 uploads)
+   * @param options.contentType - The MIME type of the content (auto-detected from filename if not provided)
+   * @param options.signal - AbortSignal to cancel the upload
    *
-   * @throws {Error} If contentLength is not provided
+   * @throws {Error} If contentLength is not provided or is negative
    * @throws {FetchError} If the upload fails
-   * @returns Promise that resolves when upload is complete
+   * @returns A Promise that resolves when the upload completes successfully
    *
    * @example
    * ```ts
-   * const file = new File(['content'], 'document.txt')
-   * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+   * // Upload a large file using streaming
+   * const file = new File(['large content'], 'video.mp4')
+   * const vaultFile = await VaultFile.fromStream({
+   *     name: 'video.mp4',
+   *     contentLength: file.size,
    *     contentType: file.type,
    *     config: { vaultUrl, authStrategy }
    * })
    *
-   * // Upload using the stream directly
    * const stream = file.stream()
    * await vaultFile.uploadStream(stream, {
    *     contentLength: file.size,
    *     contentType: file.type
    * })
+   * console.log('Upload complete!')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Upload with progress tracking
+   * const vaultFile = await VaultFile.fromStream({
+   *     name: 'document.pdf',
+   *     contentLength: fileSize,
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * // Create a transform stream to track progress
+   * let uploaded = 0
+   * const progressStream = new TransformStream({
+   *     transform(chunk, controller) {
+   *         uploaded += chunk.length
+   *         console.log(`Uploaded ${uploaded}/${fileSize} bytes`)
+   *         controller.enqueue(chunk)
+   *     }
+   * })
+   *
+   * await vaultFile.uploadStream(
+   *     originalStream.pipeThrough(progressStream),
+   *     { contentLength: fileSize }
+   * )
    * ```
    */
   async uploadStream(stream, options) {
@@ -872,10 +1130,48 @@ class VaultFile {
     });
   }
   /**
-   * Deletes the file from the vault.
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * Permanently deletes this file from the vault.
+   *
+   * This operation removes the file metadata and content from the vault. This action cannot be
+   * undone. Any vault references or permalinks to this file will become invalid after deletion.
+   * Note: This does not automatically delete child files in hierarchical relationships.
+   *
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the deletion request fails
+   * @returns A Promise that resolves when the deletion completes successfully
+   *
+   * @example
+   * ```ts
+   * // Delete a file
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * await vaultFile.delete()
+   * console.log('File deleted successfully')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Delete with confirmation
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * if (confirm('Are you sure you want to delete this file?')) {
+   *     await vaultFile.delete()
+   * }
+   * ```
    *
+   * @example
+   * ```ts
+   * // Delete with abort signal
+   * const controller = new AbortController()
+   * await vaultFile.delete({ signal: controller.signal })
+   * ```
    */
   async delete(options) {
     if (!this.id) {
@@ -888,13 +1184,51 @@ class VaultFile {
     });
   }
   /**
-   * Creates a permalink for the file.
-   * @param params - The parameters for the permalink
-   * @param params.expiresIn - The number of seconds the permalink will be valid for
-   * @param options - The options for the request
-   * @param options.signal - The signal to abort the request
+   * Creates a new shareable permalink for this file.
+   *
+   * A permalink is a public URL that allows anyone with the link to access the file without
+   * authentication. The permalink can optionally expire after a specified duration. This is
+   * useful for sharing files with external users or embedding files in public content.
+   *
+   * @param params - Optional parameters for permalink creation
+   * @param params.expiresIn - Number of seconds until the permalink expires (optional, defaults to server setting)
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @throws {Error} If the file ID is not set
+   * @throws {Error} If the workspace ID is not available (call {@link populateMetadata} first)
+   * @throws {FetchError} If the permalink creation fails
+   * @returns A Promise that resolves to a Permalink instance
+   *
+   * @example
+   * ```ts
+   * // Create a permanent permalink
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * await vaultFile.populateMetadata() // Required to get workspace ID
+   * const permalink = await vaultFile.createPermalink()
+   * console.log('Share this link:', permalink.url)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Create a permalink that expires in 24 hours
+   * await vaultFile.populateMetadata()
+   * const permalink = await vaultFile.createPermalink({
+   *     expiresIn: 24 * 60 * 60 // 24 hours in seconds
+   * })
+   * console.log('Link expires at:', permalink.expiresAt)
+   * ```
    *
-   * @returns The permalink for the file
+   * @example
+   * ```ts
+   * // Create a short-lived sharing link (1 hour)
+   * await vaultFile.populateMetadata()
+   * const permalink = await vaultFile.createPermalink({ expiresIn: 3600 })
+   * // Send permalink.url to user
+   * ```
    */
   async createPermalink(params = {}, options) {
     if (!this.id) {
@@ -910,11 +1244,51 @@ class VaultFile {
     }, options);
   }
   /**
-   * Gets a list of the valid permalinks for the file.
+   * Retrieves all active permalinks associated with this file.
+   *
+   * This method fetches all permalinks that have been created for this file and are still
+   * valid (not expired or deleted). Each permalink is returned as a Permalink instance
+   * with full details including URL, expiration date, and other metadata.
+   *
    * @param options - Additional options for the request
-   * @param options.signal - Abort signal
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the request to fetch permalinks fails
+   * @returns A Promise that resolves to an array of Permalink instances
    *
-   * @returns The permalinks for the file
+   * @example
+   * ```ts
+   * // List all permalinks for a file
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://file-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const permalinks = await vaultFile.getPermalinks()
+   * permalinks.forEach(permalink => {
+   *     console.log('URL:', permalink.url)
+   *     console.log('Expires:', permalink.expiresAt || 'Never')
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Check if any permalinks exist
+   * const permalinks = await vaultFile.getPermalinks()
+   * if (permalinks.length > 0) {
+   *     console.log(`This file has ${permalinks.length} active permalink(s)`)
+   * } else {
+   *     console.log('No active permalinks')
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Find non-expiring permalinks
+   * const permalinks = await vaultFile.getPermalinks()
+   * const permanent = permalinks.filter(p => !p.expiresAt)
+   * console.log(`Found ${permanent.length} permanent links`)
+   * ```
    */
   async getPermalinks(options) {
     if (!this.id) {
@@ -927,6 +1301,273 @@ class VaultFile {
     });
     return permalinks.map((data) => new Permalink(this.config, data));
   }
+  /**
+   * Retrieves all child files in the hierarchical file relationship.
+   *
+   * This method queries files that have this file set as their parent (via parentId).
+   * Returns an empty array if the file has no children or if the file doesn't exist.
+   * The returned children are VaultFile instances with populated metadata but no content.
+   *
+   * @param params - Optional parameters for filtering and request control
+   * @param params.mimeType - Filter children by MIME type (e.g., 'image/png', 'application/pdf')
+   * @param params.includeDeleted - Whether to include deleted child files (default: false)
+   * @param params.limit - Maximum number of children to return (default: 100)
+   * @param params.offset - Number of children to skip (default: 0)
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the request
+   *
+   * @returns An array of VaultFile instances representing the child files
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the request to fetch children fails
+   *
+   * @example
+   * ```ts
+   * // Get all children of a file
+   * const parent = await VaultFile.fromVaultReference({
+   *     reference: 'vault://parent-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const children = await parent.getChildren()
+   * console.log(`Found ${children.length} child files`)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Get only image children
+   * const parent = await VaultFile.fromVaultReference({
+   *     reference: 'vault://parent-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const imageChildren = await parent.getChildren({ mimeType: 'image/png' })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Get children with pagination
+   * const parent = await VaultFile.fromVaultReference({
+   *     reference: 'vault://parent-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   * const firstPage = await parent.getChildren({ limit: 10, offset: 0 })
+   * const secondPage = await parent.getChildren({ limit: 10, offset: 10 })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Use with abort signal for cancellable requests
+   * const controller = new AbortController()
+   * const children = await parent.getChildren({}, { signal: controller.signal })
+   * // Later: controller.abort()
+   * ```
+   */
+  async getChildren(params = {}, options) {
+    if (!this.id) {
+      throw new Error("File ID is not set");
+    }
+    const query = {};
+    if (params.mimeType) {
+      query.mimeType = params.mimeType;
+    }
+    if (params.includeDeleted) {
+      query.includeDeleted = params.includeDeleted ? "true" : "false";
+    }
+    if (params.limit !== void 0) {
+      query.limit = params.limit.toString();
+    }
+    if (params.offset !== void 0) {
+      query.offset = params.offset.toString();
+    }
+    const response = await this._fetch({
+      method: "GET",
+      path: `files/${this.id}/children`,
+      signal: options?.signal,
+      query
+    });
+    return response.files.map((data) => new VaultFile({
+      config: this.config,
+      id: data.id,
+      name: data.originalFileName ?? void 0,
+      metadata: data
+    }));
+  }
+  /**
+   * Iterates through all child files with automatic pagination.
+   *
+   * This method returns an async iterator that automatically fetches pages of children
+   * as you iterate through them. This is useful when you have a large number of children
+   * and want to process them without loading all of them into memory at once.
+   *
+   * @param params - Optional parameters for filtering and pagination
+   * @param params.pageSize - Number of children to fetch per page (default: 100)
+   * @param params.mimeType - Filter children by MIME type (e.g., 'image/png', 'application/pdf')
+   * @param params.includeDeleted - Whether to include deleted child files (default: false)
+   * @param options - Additional options for the request
+   * @param options.signal - AbortSignal to cancel the iteration
+   *
+   * @returns An async iterator that yields VaultFile instances
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the request to fetch children fails
+   *
+   * @example
+   * ```ts
+   * // Iterate through all children
+   * const parent = await VaultFile.fromVaultReference({
+   *     reference: 'vault://parent-id',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * for await (const child of parent.iterateChildren()) {
+   *     console.log(`Processing child: ${child.name}`)
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Iterate with filters and custom page size
+   * for await (const child of parent.iterateChildren({
+   *     pageSize: 50,
+   *     mimeType: 'image/png'
+   * })) {
+   *     console.log(`Processing image: ${child.name}`)
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Use with abort signal
+   * const controller = new AbortController()
+   * try {
+   *     for await (const child of parent.iterateChildren({}, { signal: controller.signal })) {
+   *         console.log(child.name)
+   *         // Can abort iteration at any time
+   *         if (someCondition) {
+   *             controller.abort()
+   *         }
+   *     }
+   * } catch (error) {
+   *     if (error.name === 'AbortError') {
+   *         console.log('Iteration cancelled')
+   *     }
+   * }
+   * ```
+   */
+  async *iterateChildren(params = {}, options) {
+    if (!this.id) {
+      throw new Error("File ID is not set");
+    }
+    const pageSize = params.pageSize ?? 100;
+    let offset = 0;
+    let hasMore = true;
+    while (hasMore) {
+      const children = await this.getChildren({
+        limit: pageSize,
+        offset,
+        mimeType: params.mimeType,
+        includeDeleted: params.includeDeleted
+      }, options);
+      for (const child of children) {
+        yield child;
+      }
+      hasMore = children.length === pageSize;
+      offset += children.length;
+      if (children.length === 0) {
+        hasMore = false;
+      }
+    }
+  }
+  /**
+   * Creates a child file from content with this file as the parent.
+   *
+   * This is a convenience method that wraps {@link VaultFile.fromContent} and automatically
+   * sets the current file as the parent. All parameters and behavior are identical to
+   * {@link VaultFile.fromContent}, except parentId is automatically provided.
+   *
+   * @param params - Parameters for creating the child file (same as fromContent, minus parentId)
+   * @param options - Additional options for the request
+   *
+   * @returns A new VaultFile instance representing the child file
+   * @throws {Error} If the parent file ID is not set
+   * @throws {FetchError} If the child file creation fails
+   *
+   * @example
+   * ```ts
+   * // Create a child file
+   * const parent = await VaultFile.fromContent({
+   *     name: 'parent.txt',
+   *     content: new Blob(['parent content']),
+   *     config: { vaultUrl, authStrategy },
+   *     upload: true
+   * })
+   * const child = await parent.createChildFromContent({
+   *     name: 'child.txt',
+   *     content: new Blob(['child content']),
+   *     upload: true
+   * })
+   * console.log('Child created with parent:', child.metadata?.parentId)
+   * ```
+   */
+  async createChildFromContent(params, options) {
+    if (!this.id) {
+      throw new Error("Parent file ID is not set");
+    }
+    return VaultFile.fromContent(
+      {
+        ...params,
+        config: this.config,
+        parentId: this.id
+      },
+      options
+    );
+  }
+  /**
+   * Creates a child file from a stream with this file as the parent.
+   *
+   * This is a convenience method that wraps {@link VaultFile.fromStream} and automatically
+   * sets the current file as the parent. All parameters and behavior are identical to
+   * {@link VaultFile.fromStream}, except parentId is automatically provided.
+   *
+   * @param params - Parameters for creating the child file (same as fromStream, minus parentId)
+   * @param options - Additional options for the request
+   *
+   * @returns A new VaultFile instance ready for streaming upload as a child
+   * @throws {Error} If the parent file ID is not set
+   * @throws {FetchError} If the child file creation fails
+   *
+   * @example
+   * ```ts
+   * // Create a child file for streaming
+   * const parent = await VaultFile.fromContent({
+   *     name: 'parent.txt',
+   *     content: new Blob(['parent']),
+   *     config: { vaultUrl, authStrategy },
+   *     upload: true
+   * })
+   * const child = await parent.createChildFromStream({
+   *     name: 'large-child.mp4',
+   *     contentLength: 100 * 1024 * 1024,
+   *     contentType: 'video/mp4'
+   * })
+   * // Upload the stream
+   * const stream = file.stream()
+   * await child.uploadStream(stream, {
+   *     contentLength: file.size,
+   *     contentType: file.type
+   * })
+   * ```
+   */
+  async createChildFromStream(params, options) {
+    if (!this.id) {
+      throw new Error("Parent file ID is not set");
+    }
+    return VaultFile.fromStream(
+      {
+        ...params,
+        config: this.config,
+        parentId: this.id
+      },
+      options
+    );
+  }
 }
 
 function isS3UrlExpired(url) {
@@ -978,7 +1619,7 @@ const URL_STRATEGIES = [
 ];
 function extractVaultFileIdFromS3Url(url) {
   if (isVaultReference(url))
-    return url.replace("vault://", "");
+    return vaultUtils.file.getFileIdFromVaultReference(url);
   try {
     if (!isVaultFileS3Url(url))
       return null;
@@ -1012,12 +1653,18 @@ function vaultClient(vaultConfig) {
       const name2 = nameOrContent;
       const content2 = contentOrNameOrOptions;
       const signal2 = options?.signal;
-      return VaultFile.fromContent({ content: content2, name: name2, config }, { signal: signal2 });
+      const parentId2 = options?.parentId;
+      const mimeType2 = options?.mimeType;
+      const upload2 = options?.upload;
+      return VaultFile.fromContent({ content: content2, name: name2, config, parentId: parentId2, mimeType: mimeType2, upload: upload2 }, { signal: signal2 });
     }
     const content = nameOrContent;
     const name = typeof contentOrNameOrOptions === "string" ? contentOrNameOrOptions : void 0;
     const signal = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.signal : options?.signal;
-    return VaultFile.fromContent({ content, name, config }, { signal });
+    const parentId = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.parentId : options?.parentId;
+    const mimeType = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.mimeType : options?.mimeType;
+    const upload = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.upload : options?.upload;
+    return VaultFile.fromContent({ content, name, config, parentId, mimeType, upload }, { signal });
   }
   function createFromReference(reference, options) {
     return VaultFile.fromVaultReference({
@@ -1030,7 +1677,8 @@ function vaultClient(vaultConfig) {
       name,
       contentLength,
       config,
-      contentType: options?.contentType
+      contentType: options?.contentType,
+      parentId: options?.parentId
     }, { signal: options?.signal });
   }
   return { createFromContent, createFromReference, createFromStream };