@meistrari/vault-sdk 1.6.3 → 1.8.0

package/dist/index.d.cts

@@ -151,6 +151,7 @@ declare 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
      *
@@ -212,7 +213,9 @@ declare 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
      *
@@ -247,12 +250,30 @@ declare 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 fromContent(params: {
         content: Blob | File;
         config: VaultConfig;
         name?: string;
+        mimeType?: string;
         upload?: boolean;
+        parentId?: string;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
@@ -265,6 +286,7 @@ declare 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
      *
@@ -287,117 +309,309 @@ declare 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 fromStream(params: {
         name: string;
         contentLength: number;
         config: VaultConfig;
         contentType?: string;
+        parentId?: string;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
     /**
-     * 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.
      *
-     * @returns The file 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.
+     *
+     * @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()
+     * ```
      */
     populateMetadata(options?: {
         signal?: AbortSignal;
     }): Promise<this | undefined>;
     /**
-     * Gets the vault reference for this file.
+     * Returns the vault URI reference for this file.
      *
-     * @returns The vault reference in the format `vault://{fileId}`
+     * 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 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(): string;
     /**
-     * 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 })
+     * ```
      */
     getFileMetadata(options?: {
         signal?: AbortSignal;
     }): Promise<FileMetadata>;
     /**
-     * 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
+     * ```
      */
     getUploadUrl(options?: {
         signal?: AbortSignal;
         expiresIn?: number;
     }): Promise<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
+     * ```
      */
     getDownloadUrl(options?: {
         signal?: AbortSignal;
         expiresIn?: number;
     }): Promise<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())
+     * ```
      */
     upload(file?: Blob, url?: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /**
-     * Downloads a file from the vault.
+     * Downloads the complete file content from the vault.
      *
-     * @param responseType - The type of the response
-     * @param options - The options for the request
-     * @param options.signal - The signal to abort the request
+     * This method fetches the entire file content and loads it into memory. For large files,
+     * consider using {@link downloadStream} instead for memory-efficient streaming. The method
+     * automatically handles fetching the download URL and retrieving the content.
      *
-     * @returns The response from the vault
+     * @param responseType - The desired response format: 'blob' (default) or 'base64'
+     * @param options - Additional options for the request
+     * @param options.signal - AbortSignal to cancel the download
+     *
+     * @returns A Promise resolving to a Blob (default) or base64-encoded string
+     * @throws {FetchError} If the download fails
      *
      * @example
      * ```ts
-     * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
-     * const content = await vaultFile.download()
+     * // Download as Blob (default)
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://file-id',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     * const blob = await vaultFile.download()
+     * console.log('Downloaded:', blob.size, 'bytes')
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Download as base64 string
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://file-id',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     * const base64 = await vaultFile.download('base64')
+     * // Use in img src: `<img src="data:image/png;base64,${base64}" />`
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Download with abort signal
+     * const controller = new AbortController()
+     * const blob = await vaultFile.download('blob', { signal: controller.signal })
+     * // Later: controller.abort()
      * ```
      */
     download(responseType?: 'blob', options?: {
@@ -407,62 +621,123 @@ declare class VaultFile {
         signal?: AbortSignal;
     }): Promise<string>;
     /**
-     * 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()
+     * ```
      */
     downloadStream(options?: {
         signal?: AbortSignal;
     }): Promise<ReadableStream<Uint8Array>>;
     /**
-     * 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.
      *
-     * @throws {Error} If contentLength is not provided
+     * @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 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 }
+     * )
      * ```
      */
     uploadStream(stream: ReadableStream<Uint8Array>, options: {
@@ -471,22 +746,98 @@ declare class VaultFile {
         contentType?: string;
     }): Promise<void>;
     /**
-     * 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 })
+     * ```
      */
     delete(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /**
-     * 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.
      *
-     * @returns The permalink for the file
+     * @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)
+     * ```
+     *
+     * @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
+     * ```
      */
     createPermalink(params?: {
         expiresIn?: number;
@@ -494,15 +845,259 @@ declare class VaultFile {
         signal?: AbortSignal;
     }): Promise<Permalink>;
     /**
-     * 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
+     *
+     * @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')
+     * })
+     * ```
      *
-     * @returns The permalinks for the file
+     * @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`)
+     * ```
      */
     getPermalinks(options?: {
         signal?: AbortSignal;
     }): Promise<Permalink[]>;
+    /**
+     * 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()
+     * ```
+     */
+    getChildren(params?: {
+        mimeType?: string;
+        includeDeleted?: boolean;
+        limit?: number;
+        offset?: number;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile[]>;
+    /**
+     * 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')
+     *     }
+     * }
+     * ```
+     */
+    iterateChildren(params?: {
+        pageSize?: number;
+        mimeType?: string;
+        includeDeleted?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<VaultFile>;
+    /**
+     * 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)
+     * ```
+     */
+    createChildFromContent(params: Omit<Parameters<typeof VaultFile.fromContent>[0], 'config' | 'parentId'>, options?: Parameters<typeof VaultFile.fromContent>[1]): Promise<VaultFile>;
+    /**
+     * 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
+     * })
+     * ```
+     */
+    createChildFromStream(params: Omit<Parameters<typeof VaultFile.fromStream>[0], 'config' | 'parentId'>, options?: Parameters<typeof VaultFile.fromStream>[1]): Promise<VaultFile>;
 }
 
 /**
@@ -539,12 +1134,21 @@ declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: {
         (name: string, content: Blob | File, options?: {
             signal?: AbortSignal;
+            parentId?: string;
+            mimeType?: string;
+            upload?: boolean;
         }): Promise<VaultFile>;
         (content: Blob | File, name?: string, options?: {
             signal?: AbortSignal;
+            parentId?: string;
+            mimeType?: string;
+            upload?: boolean;
         }): Promise<VaultFile>;
         (content: Blob | File, options: {
             signal?: AbortSignal;
+            parentId?: string;
+            mimeType?: string;
+            upload?: boolean;
         }): Promise<VaultFile>;
     };
     createFromReference: (reference: string, options?: {
@@ -553,6 +1157,7 @@ declare function vaultClient(vaultConfig: VaultConfig): {
     createFromStream: (name: string, contentLength: number, options?: {
         contentType?: string;
         signal?: AbortSignal;
+        parentId?: string;
     }) => Promise<VaultFile>;
 };